SSO with OpenID Connect

For customers with their own identity server that complies with the 🔗 OpenID Connect (OIDC) standard, setting up single sign-on (SSO) is relatively easy. It involves a number of steps from both the customer and Drillster. This page describes the steps required on the part of the customer.

If you are interested in creating an SSO integration with Drillster using Open ID Connect, please contact support@drillster.com.

Registering a client application

Drillster will be acting as a client application to your OIDC server, so a client application must be registered at your OIDC server. This can be done in one of two ways:

  1. Drillster registers it
  2. You register it

Drillster registers it

The easiest and most secure way to do this is to allow Drillster to register it themselves on your OIDC server. This requires that your OIDC server supports either Dynamic Client Registration, or a web interface that Drillster can use. All you need to do is provide Drillster Support the endpoint or web interface URL (and possibly credentials) to register the client application. Drillster will register the client application and set up the SSO in the Drillster platform for you. Once that is done, you can use SSO.

You register it

If your OIDC server does not support this, you have to set up the client application for Drillster yourself. One of the required properties is the redirect URI, which is the Drillster URI where the user is sent to after successful authentication. Since part of this URI is custom for your OIDC integration with Drillster, you'll need to request it from Drillster first.

Selecting the authentication flow

Drillster supports two OIDC flows for authentication:

Authorization Code Flow

After successful authentication, the user is sent back to Drillster with an authorization code, which is used by Drillster to request an ID token from your OIDC server. The ID token contains identity information of the authenticated user, and is used by Drillster to sign the user in to his Drillster account.

Form Post Response Mode

With this flow, an ID token, instead of an authorization code, is sent from your OIDC server to Drillster by the user agent (browser) after successful authentication. This eliminates need to use an authorization code to obtain the ID token. This removes the burden of having, sharing, and renewing client credentials. For this reason, Drillster recommends using the Form Post Response Mode.

To use the Form Post Response Mode, please ensure that you OIDC server is capable of and configured to support response_type=id_token and response_mode=form_post request parameters in the authorization request.

💡 Microsoft Entra ID / Azure AD

Microsoft Entry ID is fully compatible with OIDC, and can be used to facilitate SSO with Drillster. Please consult the Drillster Entra ID guide for more details on how to enable ID tokens and configuring custom claims.

Providing client application info to Drillster

After selecting an authentication flow, and registering the client application, please provide the following information to Drillster:

  • Client ID
  • Client secret (only for Authorization Code Flow, see security warning below)
  • The URI of the /.well-known/openid-configuration endpoint (or the tenant ID if you are using Microsoft Entra ID)

⚠️ Warning

Since the client secret is highly sensitive information, it is very important to send this information in a secure way. Do not send it by email! Please get in touch with Drillster Support to agree on a secure way to hand over the client secret.

If your OIDC server does not have a /.well-known/openid-configuration endpoint, please provide the following information to Drillster:

  • Authorization URI
  • Token URI
  • JWKS URI

Drillster will set up the SSO in the Drillster platform for you. Once that is done, you can use SSO.

Using SSO

Once Drillster has configured SSO for you, you will receive an SSO base URI. You use this URL to send your users to the Drillster web platform and provide single sign-on. The SSO base URI looks like this:

https://www.drillster.com/daas/authenticate/oauth/{third_party}

The third_party is a unique ID for your SSO configuration. To send your users to a specific page in the Drillster web platform, you append the URL of this location to the base URI as a request parameter:

https://www.drillster.com/daas/authenticate/oauth/{third_party}?redirectUrl={redirect_url}

Examples of redirect URLs are:

  • /connector/player/{playable_id} — the Player for a specific playable (e.g. a drill)
  • /console/learn/ — the user's library page
  • /console/ — the user's home page

Please ask Drillster Support for help with specific redirect locations.

 

Last updated on