Setting up a custom SSO workflow

The purpose of this document is to describe the requirements for setting up and implementing a custom service provider initiated SSO workflow with Creatable.

Single sign-on steps for accessing Creatable

1. User navigates to login.creatable.io
2. User chooses “Continue with SSO”
3. User enters email address that was configured for the client account for use with SSO, for example “user@brand.com”
4. Creatable validates the SSO domain
5. User is directed to identity provider url of the domain
6. User authenticates successfully
7. User is redirected back to Creatable
8. User lookup is performed
9. User is authorized for access to creatable
10. User is directed to the Creatable dashboard

In a case where a user account has not been provisioned with Creatable, the user will be displayed a message that their account has not been set up yet.

Custom SSO requirements

Our SSO solution utilizes an OAuth standard with JWT. In order to set up a custom single sign-on workflow, several pieces of information are required to configure the connection.

Domain
A domain must be provided that corresponds with the user's email address for the purposes of identification of the identity provider. For example, "brand.com".

Identity provider URL
This is the url that is provided by the client to Creatable that directs the user through an authentication process with the identity provider.

Public key
The identity provider will provide to Creatable a public key used to decrypt the ‘token’ parameter. This key must be generated using the RS256 algorithm.

To generate a public & private key, this can be done using an OpenSSL command line:

Once the public and private keys have been generated, send the public key file to your client success account representative, along with the Identity provider authentication URL and they will complete the set up on the Creatable side.

Identity provider URL request parameters

Sample URL structure

Callback URL parameter (callback_url)
This url encoded value is provided by Creatable and passed to the identity provider.

When redirecting the user to the callback URL from the identity provider, the identity provider must append the 'token' parameter to the callback_url:

 

Token parameter (token)
Token (JWT) consisting of 3 parts (Header, Payload, Signature). The payload must contain the user’s email address. When encrypting the token parameter, you must use the RS256 algorithm.

 

Header

The header portion of the JSON token must contain the following data:

Payload

The payload of the JSON token must contain the authorized user’s email address in the following structure:

Base64 and URL encode the header and payload values, then concatenate them: header + “.” + payload to create the string to be encrypted.

Encrypt that value using the RS256 algorithm with the private key, and the final output is the value of the “signature" portion of the token.

The completed token value should be: header + “.” payload + "." + signature.

 

Sample callback URL structure

Identity provider appends the token parameter to the callback url:

Final assembled URL format example:

https://app.creatable.io/v3/api/user/sso//authenticate?token=

Testing

In order for a custom SSO workflow to be implemented, testing credentials must be provided by the client, so that our client success team can validate that the configuration is working as expected. Testing is performed against a publicly available environment provided by the identity provider.

If needed, separate environments can be configured for SSO testing. Please let your client success account manager know if this is the case.