Implementing SSO

Contents

Logging in

After SSO is enabled, as described in Configuring SSO, when users access a page, that requires authentication, they are redirected to the Remote login URL, that has been specified in the configuration. The additional argument returnto, that will be added to this redirect URL, will hold the URL of the Kayako SSO end point.

Thus, if the Remote login URL is https://redmine.brewfictus.com/login, the redirect URL will be, e.g.:

https://redmine.brewfictus.com/login?returnto=https%3A%2F%2Fbrewfictus.kayako.com%2Fagent%2FBase%2FSSO%2FJWT%2F%26type%3Dagent%26action%3D%2Fagent%2F

After the remote login page successfully authenticates the user, it will need to generate a valid JWT token and redirect back to the return URL, that has been passed in the returnto argument.

See also Redirecting to Kayako below.

Generating JWT token

The JWT token should consist of three parts separated by dots (.). Each of these parts should be base64-encoded.

First two parts of the JWT token are JSON objects.

For more details check RFC 7519.

The header JSON object delivers properties of the JWT token:

Claim Mandatory Description
typ
Type: always JWT
alg
Algorithm: HS256, HS384 or HS512

Example

{
    "typ": "JWT",
    "alg": "HS256"
}

Payload

The payload JSON object, which should be in the middle, delivers user data:

Claim Mandatory Description
iat
Issued At: the time, at which the token was generated, in the number of seconds since the Unix epoch
jti
JWT token ID: the unique identifier of the token
email
The email address of the user
name
The full name of the user
role Possible values: customer, agent, admin or owner
Default: customer
external_id A unique identifier of the user in the SSO service
locale
organization
phone_number Must be unique to the user
tags Comma-separated list of tags
picture The URL to the avatar image of the user

Kayako first attempts to identify the user by the external_id claim, if it's specified, and then by the email claim. The external_id claim is to be set to a unique ID of the user's account in the SSO service, but can be omitted.

If the user does not exist in Kayako, it will be created with all the specified attributes. If the user exists, values of the claims name, locale, phone_number, tags and picture will update (replace) existing values in the user's profile.

The value of the organization claim is ignored for owners, admins and agents. For customers it is used, only when the user is created.

The role claim should always be specified, when the JWT token is used to access API.

Example

{
    "iat": 1464285714,
    "jti": "1tEC3NRiaxPnRo0gB03YGGt5xUmUhLLm",
    "email": "jordan.mitchell@brewfictus.com",
    "name": "Jordan Mitchell",
    "role": "admin",
    "external_id": "1407638772888867",
    "locale": "en-us",
    "organization": "Brewfictus",
    "phone_number": "+14156792019",
    "tags": "Support, Manager",
    "picture": "https://brewfictus.kayako.com/avatar/get/63d1d45c-408a-55be-87ac-ad09470ea742"
}

Signature

The last part of the JWT token is digital signature of the two previous parts, which is calculated as follows:

hmac_sha(base64($header) + '.' + base64($payload), $shared_secret)

Here, $shared_secret is the secret, which is specified in SSO configuration.

The signature must use HMAC SHA256, SHA384 or SHA512 algorithm. The used algorithm must also be specified in the alg claim of the JWT header.

Redirecting to Kayako

Having generated the JWT token, the remote login page must deliver it to Kayako using the URL, that was passed in the returnto argument of the Remote login URL (see also Logging in above). The token must be appended to this URL in the jwt argument, as in the following example:

https://brewfictus.kayako.com/agent/Base/SSO/JWT/?type=agent&action=/agent/&jwt=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE0NjQyODU3MTQsImp0aSI6IjF0RUMzTlJpYXhQblJvMGdCMDNZR0d0NXhVbVVoTExtIiwiZW1haWwiOiJqb3JkYW4ubWl0Y2hlbGxAYnJld2ZpY3R1cy5jb20iLCJuYW1lIjoiSm9yZGFuIE1pdGNoZWxsIn0.HvwWzFF4eOzn4xKNw6sMGzKk6kl91FhgiG0SP2SHXZk

If the JWT token is valid, Kayako will let the user log in and then will redirect the browser to the page, which is specified in the action argument.

So, if you want to redirect the user to a custom page after successful login, you need to modify the value of the action argument. This argument holds the path of the page, e.g., /agent/cases/101.

In the case of an error, Kayako will redirect the user back to the Remote login URL. If you want to let the user try logging in without SSO instead, add the &fallback=true to the return URL.

Handling errors

If an error occurs while processing the JWT token, Kayako will redirect the user back to the Remote login URL, having added three additional arguments, that describe the error:

  • message contains the description of the error
  • code is the numeric identifier of the error, usually 0
  • type is always error