Custom SSO (Using JWT) – Thinkific Developers

NOTE: Thinkific now supports SSO through the OpenID Connect Standard, which is widely supported and straightforward to implement. We recommend first exploring this OIDC Approach and leveraging the following custom implementation only if it does not meet your needs. Learn more about setting up OpenID Connect SSO.

SSO, or Single Sign-On, allows you to connect your Identity Provider to Thinkific to provide a seamless, logged-in experience for users when navigating between your primary experience and your Thinkific site.

Plan access & Requirements

SSO is a feature reserved for creators that are on a Thinkific Plus plan.
Software development experience or resources.

Note: At this time the SAML standard is not supported for SSO with Thinkific.

How It Works

First a user will sign into your external site. Once they have been authenticated, your application will construct a token (JWT) and redirect to Thinkific’s SSO URL with this token as a query string parameter. Thinkific deconstructs this payload and either finds the user and signs them in, or if they don’t already have an account on your Thinkific site, creates an account and signs them in.

The Thinkific SSO URL

The Thinkific SSO URL is the URL on your Thinkific school that you redirect to after a user has successfully authenticated in your system. It has the following structure:

https://{your-school}.thinkific.com/api/sso/v2/sso/jwt?jwt={payload}&return_to={url to return to}&error_url={url to redirect to in the case of an error}

The jwt parameter is the JWT payload that you construct and is REQUIRED.
The return_to is the url that you want the user to be redirected to after signing in to your Thinkific school. It is OPTIONAL.
The error_url is the url that you want the user to be redirected to in the case of an error. This is OPTIONAL.
If the return_to url is not supplied, the user will be redirected to their default page within your Thinkific school.
If the error_url is not supplied, the user will be redirected to the return_to url that you supplied OR, if no return_url is supplied, to a generic Thinkific error page.

The SSO Signing Secret

To construct and sign the JWT payload your must use a SSO signing secret. This secret can be an API Access Token's SSO signing secret, or Thinkific API Key. The API Access Token SSO signing secret can be found when you generate a new API Access Token on your Thinkific admin dashboard's Settings > Code & Analytics page. It is only shown when the token is first created, and can not be retrieved afterwards. The API key can be found in the API Key section on your Thinkific admin dashboard's Settings > Code & Analytics page. For new implementations, please use the API Access Token's SSO signing secret when possible.

The JWT Payload

Your application must construct the JWT payload and sign it using your SSO signing secret mentioned in the previous section. The best practice for security is to generate the JWT token on a server and then retrieve it from the client side, rather than exposing the JWT shared secret in the client-side JavaScript.

Note: Do not base 64 encode your SSO signing secret when signing your JWT token. Our application expects the SSO signing secret as-is when verifying your JWT token.

The JWT payload is typically constructed as a hash. The following attributes are supported:

{
  "first_name": "Thinkific",
  "last_name": "Admin",
  "email": "thinkific@thinkific.com",
  "iat": 1520875725
  "external_id": "thinkific@thinkific.com",
  "bio": "Mostly harmless",
  "company": "Thinkific",
  "timezone": "America/Los_Angeles",
  "locale": "pt-BR"
}

email (required) - the email of the authenticated user. If external_id is not supplied, email will be used as the unique identifier.
first_name (required)- the first name of the authenticated user.
last_name (required)- the last name of the authenticated user.
iat (required) - must be the number of seconds since UNIX epoch. This is essentially the time that the JWT payload was issued.
external_id - an identifier for the authenticated user. This is typically the id of the user in your system. This is OPTIONAL, but if supplied will be used as the unique identifier of the user. What this means is that when your student is trying to log in and you have included external_id in the payload, the Thinkific database will look for a user with that external_id. If that user is not found, the system will attempt to create them.
bio - a textual bio of the user. This is OPTIONAL.
company - the user's company. This is OPTIONAL.
timezone - the user's timezone abbreviation (as defined here: https://www.iana.org/time-zones). This is OPTIONAL.
locale - the user's locale (as defined on RFC4646). Allow students to override the site language should be enabled on Settings -> Language settings.

There are various libraries for working with JWT. A list can be found here. We recommend using the HS256 algorithm.

One thing to be aware of is that the JWT payload is merely encoded and signed, not encrypted, so don't put any sensitive data in the hash table. JWT works by serializing the JSON that is being transmitted to a string. It then base 64 encodes that string and then makes an HMAC of the base 64 string which depends on the shared secret. This produces a signature that the recipient side can use to validate the user.

The return_to parameter

After a user is authenticated in your system, it should redirect to your Thinkific school's SSO URL. As part of the redirect URL, you can append a return_to query string parameter that is an encoded URL that the user will be returned to after the sign in to your Thinkific school is complete. For example:

https://{your-school}.thinkific.com/api/sso/v2/sso/jwt?jwt={payload}&return_to=https%3A%2F%2Fyoursite.com

The error_url parameter

When attempting to use the SSO, errors can occur. For example, the user's email address may be improperly formatted. In these cases, you may want the user to be redirected to an error page of your choosing. For example:

https://{your-school}.thinkific.com/api/sso/v2/sso/jwt?jwt={payload}&return_to=https%3A%2F%2Fyoursite.com&error_url=https%3A%2F%2Fyoursite.com/sso_error

Error Handling

If an error occurs, the user will not be signed into your Thinkific school. There are several cases when this might occur:

Your code does not provide the JWT payload
Your JWT payload is not correctly signed
Your JWT payload is expired - this is based on the age of the IAT parameter. Thinkific allows a 120 second leeway of accuracy to account for things like clock skew.
A validation error occurs when creating a new user in your Thinkific school (if one of the required parameters is missing, for example).
Some other unforeseen exception occurs.

If an error does occur, and you have provided a return_to parameter, Thinkific's SSO will not sign the user in and will redirect to the supplied return_to URL with 2 parameters:

kind - the type of error (currently one of 6 possibilities: jwt, validation, expired_token, invalid_iat and unspecified)
message - the error message

If an error does occur, and you have provided an error_url parameter, Thinkific's SSO will not sign the user in and will redirect to the supplied error_url with the same parameters as above.

The error_url is used preferentially to the return_to url if both are provided

If an error occurs and you have not provided a return_to parameter, Thinkific's SSO will not sign the user in and will display the error message on the default page of your Thinkific school.

Validation failed email has already been taken

If your user already exists in your Thinkific site but doesn’t have an external_id assigned to them, the SSO will try to create a new user with that external_id. This will fail because the email address has already been taken. So don’t use external_id unless ALL of your users are created using SSO.

If you’re creating users with the API, you can set the external_id in the POST /user request but the external_id of these users cannot be retrieved by GET /users or updated by PUT /users/{id}.

Customizing Your Site Theme

Often when using SSO, you'll want to keep your student users from signing up in the traditional manner.

In order to customize your Thinkific site theme on the checkout page, you must have Two-Step Checkout enabled (and not the Performance Checkout). Please reach out to your Launch Specialist or CSM for next steps.

There are three steps we recommend to customize your Thinkific site theme. You can read more about customizing here.

Catch-all redirect in your theme's meta_tags to redirect your students from the Thinkific Sign In or Sign Up pages to your external site. Example:

<script>
  window.location.href = 'https://www.yoursite.com';
</script>

Redirect the "Sign In" link in your header to your external site.
Redirect the "Buy" button for users who are not signed in to your external site.

If you are using the Performance Checkout instead of the Two-Step Checkout, it is still possible to achieve the same results on your site. This can be done through your site footer code and by making changes to your site pages.

Safelisting Your Domain

You can designate permitted domains to ensure that your students using SSO will only be sent to websites that you trust. To safelist your domain, see Single Sign On (SSO): Safelisted Domains