⚒️Configuring SSO with Auth0

Getting started

Create a new Auth0 tenant for your organization.

Add an Application

This application will represent the Cubu web application to Auth0 and your users. It manages the login experience and is the gateway to obtain the access tokens to the cubu API.

• Go to Applications > Applications in the auth0 portal and click the Create Application button.

• In the Create application dialog, select the Single Page Web Applications application type and give the application an easy-to-recognize name. This guide will use cubu-client as the name in future references.

• In the Settings tab of the newly created app, write down the Domain and Client ID values. These will be used later to configure the SSO settings for your organization inside of Cubu.

  • Scroll down to the Application URIs section and fill in the following values:

    • Application Login URI: https://YOUR_ORG_SUBDOMAIN.app.cubu.com

    • Allowed Callback URLs: https://YOUR_ORG_SUBDOMAIN.app.cubu.com

    • Allowed Logout URLs: https://YOUR_ORG_SUBDOMAIN.app.cubu.com/logout

    • Allowed Web Origins: https://YOUR_ORG_SUBDOMAIN.app.cubu.com

    • Allowed Origins: https://YOUR_ORG_SUBDOMAIN.app.cubu.com

  • Scroll down to the page's end and open the Advanced Settings section.

    • Using the "Grant Types" tab, ensure the Authorization Code is checked and everything else unchecked.

  • Don’t forget to save your changes.

• Switch to the Connections tab and ensure only the connections you intend to use to log into Cubu are selected. Social connections are discouraged.

Add an API

This API will be a stand-in for the Cubu API, for which tokens are issued.

• Go to Applications > APIs in the auth0 portal and click the Create API button.
• In the Create API dialog, give the API an easy-to-recognize name and an identifier that will be used when access tokens are issued. We recommend https://api.cubu.com as an identifier. This guide will use cubu-api as the name in future references. The Signing Algorithm should be kept at RS256.
• Write down the API’s Identifier, which will be used later when configuring SSO in your Cubu organization.

• The default settings for the API are fine and can be kept as is.

Add Required Claims to the Access Token

Cubu relies on having the user’s email claim in the access token for user creation. It also (optionally) uses the user’s name claim to initialize the user’s initial display name in the app. To ensure the access token contains the relevant information, a custom Action needs to be added to your authorization server.

• Go to Actions > Library and click on the Build Custom button.
• Give the action a name. Something meaningful like "Add claims to token".

• Select the “Login / Post Login” trigger. Keep the recommended runtime (Node 18 at the moment of authoring this paper)
• Add code to set the email and name claims on the accessToken from an authenticated user, and click Deploy.

exports.onExecutePostLogin = async (event, api) => {
  if (event.authorization) {
    api.accessToken.setCustomClaim('email', event.user.email);
    api.accessToken.setCustomClaim('name', event.user.name);
  }
};

• Go to Actions > Flows and click Login.

  Select the Custom tab on the right panel, and drag your “Add claims to token” action in between "Start" and "Complete" on the graph:

Configuring your Organization in Cubu

• Log in to your organization in cubu with the user that created the organization in cubu (organization owner) and navigate to the SSO page of the Settings tool in the Admin tools tool-belt
• Click the Enable SSO button and enter your auth provider’s information in the Enable SSO dialog in the following way:

  • Identity service provider (ISP): Auth0

  • Authority: The cubu-client application’s domain, preceded by https://

  • Audience: The cubu-api API’s identifier (e.g.,: https://api.cubu.com)

  • Client ID: The cubu-client application’s client ID.

  • Organization owner email: The email of the organization user in your auth0 tenant that will be associated with the current application owner user’s cubu account.
• After clicking Enable SSO in the dialog, the page should refresh, prompting you to log in.