In order for Tourbuzz to handoff customer authentication responsibility to the provider we have implemented a single sign-on solution that is secure and straighforward to implement.

We drew a bunch of inspiration from Zendesk's SSO implementation. In fact, we've been happily using the Zendesk single sign-on for our support site.

If you have any questions please feel free to ask.

JWT: JSON Web Token

Provider ID: This is a specific ID to your organization as defined in Tourbuzz's system.

Customer ID: The customer ID is specific to one of your customers/agents. You are responsible for maintaining the association between your customers and their Tourbuzz customer ID.

Shared Key: A key generated by Tourbuzz that will be shared with you, used in signing your JWT

Remote Login URL: An absolute path to your login page.

1. Have a conversation with Tourbuzz to ensure SSO is the right solution.
2. Tourbuzz SSO only works for providers with a custom tour domain configured. Configure it now!
3. Have Tourbuzz generate a shared key and Tourbuzz will share it with you.
4. Prepare your remote login URL and share it with Tourbuzz.
5. Once Tourbuzz confirms your SSO configurations are deployed, you should be ready to begin implementation.

1. An unauthenticated customer clicks a link to the Tourbuzz Client Panel.
2. Tourbuzz SSO mechanism recognizes the custom tour domain, SSO is configured, and that the user is not authenticated.
3. The user is redirected to your remote login URL (configured by Tourbuzz, please contact us if this needs changed)
4. A script on your side authenticates the user
5. Your script builds a JWT token and redirects your customer back to Tourbuzz with the token in a GET param (jwt)
6. Tourbuzz will check the token and its contents, if valid the customer will be authenticated and have access to their Client Panel

/**
 * Sample controller that accepts a post from your login form
 */
$app->post('/login', function (Request $request) use ($app) {
    if (
        // The user credentials are valid
    ) {
        $tourbuzzCustomerId = 123; // You store this id on your side to associate your customers with their Tourbuzz customer ID
        $yourTourbuzzDomain = 'tours.yourcompany.com'; // Or www.tourbuzz.net
        $yourTourbuzzProviderId = 1; // Your Tourbuzz provider ID

        $jwt = getToken($tourbuzzCustomerId);
        
        // http://[your custom tours domain or www.tourbuzz.net]/api/auth/client/jwt?jwt=[token]&provider_id=[your provider id]
        $url = sprintf(
            'http://%s/api/auth/client/jwt?jwt=%s&provider_id=%s',
            $yourTourbuzzDomain,
            urlencode($jwt->__toString()),
            urlencode($yourTourbuzzProviderId)
        );

        if ($request->query->has('return_to')) {
            $url = $url.'&return_to='.urlencode($request->query->get('return_to'));
        }

        return $app->redirect($url);
    }

    $app['session']->set('error', 'login failed');

    return $app->redirect('/login');
});

/**
 * Sample function to generate a JWT compatible with Tourbuzz's SSO
 */
function getToken($tourbuzzCustomerId)
{
    $sharedKey = '[your shared key]';
    $signer = new \Lcobucci\JWT\Signer\Hmac\Sha256();

    return (new \Lcobucci\JWT\Builder())
        ->setIssuedAt(time()) // Configures the time that the token was issue (iat claim)
        ->set('customerId', $tourbuzzCustomerId)
        ->sign($signer, $sharedKey)
        ->getToken(); // Retrieves the generated token
}

The /api/auth/client/jwt endpoint accepts a return_to GET param. This can be populated with a URL encoded absolute path where you'd like the customer to be redirected to after they successfully authenticate.

The return_to GET param might be set in the inital redirect from Tourbuzz to your authentication system. If it is set you can simply pass it back to Tourbuzz after a successful authentication. This will ensure your customer's prelogin destination will be reached after the SSO succeeds.