Integrating Auth0 OIDC

This document describes Cloud Identity Plane integration with Auth0 working as an external IDP. CIP allows users authenticated via Auth0 to be seamlessly authenticated into the CIP platform as well.

Prerequisites

  • You have an application created on the Auth0 side with a tenant user. If you want to create one, please check the Auth0 getting started guide.

Get Auth0 app data for CIP

Warning

The instructions in this section come from Auth0 and they are up-to-date at the time of writing only. Please refer to the official Auth0 documentation if the steps below are outdated.

Video

Log in to your Auth0 account and copy the Auth0 application Domain, Client ID, Client secret, and OpenID Configuration as shown in the video below.

Note

The Allowed Callback URLs field is empty when you configure the app for the first time. You will need to enter this information after you have configured the Auth0 IDP on the CIP side.

Instruction

  1. Log in to Auth0 management dashboard.

  2. Navigate to Applications and open the application for which you want to authenticate users using Auth0. Please refer to the Auth0 application documentation for help if needed.

  3. Navigate to settings to gather the application keys required to communicate with Auth0. You need the following information:

    • Domain
    • Client ID
    • Client Secret
    • OpenID Configuration (under Advanced Settings)
  4. Proceed to configuring the Auth0 rule for CIP.

Configure Auth0 rule to ensure the correct claim format

Auth0 returns updated_at claim in the id_token in a format similar to 2021-03-19T13:22:15.471Z, which is not OIDC-compliant. The below rule must be set in Auth0 to override the claim to return in the numeric format, such as 1616160135471:

function (user, context, callback) {
  context.idToken = context.idToken || {};
  context.idToken.email = user.email;
  context.idToken.name = user.name;
  context.idToken.nickname = user.nickname;
  context.idToken.updated_at = Date.now();
  callback(null, user, context);
}

Watch the video or read the instruction below to learn how to add the rule.

Video

Log in to your Auth0 account and proceed as shown in the video.

Instruction

  1. Log in to your Auth0 account.

  2. Navigate to Rules and create a new rule from the Empty Rule template.

  3. Specify the name and add the rule script.

  4. Save your changes.

Configure CIP as a service provider

Video

As you can see, the OIDC icon representing Auth0 is available in the log-in page as a result.

Instruction

  1. Login to CIP as administrator.

  2. Navigate to Identity Providers and click Register Identity Provider.

  3. Select the OIDC icon to register Auth0 IDP.

  4. Fill out and submit the form to register Auth0 IDP.

    Field Description
    Name The name to identify the Auth0 IDP.
    Description A text description of the intended purpose.
    Logo URL An icon to display on the login page for the Auth0 IDP login.
    Client ID The unique identifier for the application received from Auth0 IDP.
    Client secret This is a secret password shared between application and Auth0 IDP, used in authentiction flows.
    Discovery URI Location to discover Auth0 IDP endpoints.
    Enabled A flag to activate the Auth0 IDP.
    Visible A flag to display Auth0 IDP icon on the login page.
    Field mapping Define mappings for incoming claims to CIP user attributes.
    Identifier field Select the user identifier field from the incoming claims.
  5. Copy the Redirect URI to be shared with Auth0 IDP.

  6. Add the Redirect URI to the Auth0 app settings in the Allowed Callback URL field. See the previous video again for reference on where to add it in the Auth0 settings.

Verify your setup

  1. Go to the CIP login page and select the Auth0 OIDC icon.

  2. Authenticate with the Auth0 account when prompted.

  3. After a successful Auth0 login, you are presented with consent form. Accept the consent form if prompted.

  4. Your user is now provisioned at CIP and redirected to the self-service page.

JWT ID Token payload

CIP federation-service requests the following scopes: openid, profile, email when authorizing to Auth0 IDP. A sample id_token payload received from Auth0 IDP is presented below.

{
  "nickname": "jdoe",
  "name": "jdoe@cloudentity.com",
  "picture": "https://s.gravatar.com/avatar/7888c83166284accaf56b8842ac0f32e?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fsd.png",
  "updated_at": 1616160135616,
  "email": "jdoe@cloudentity.com",
  "email_verified": false,
  "iss": "https://dev-73gcfkem.us.auth0.com/",
  "sub": "auth0|6042743a3f8473006f562bf8",
  "aud": "R2m4RsFhxLjnD8Y03gN4jTMhTLYSQYfo",
  "iat": 1616160136,
  "exp": 1616196136
}

Tip

The id_token is captured in federation-service logs and can be accessed using the following command:

docker logs -n 100 `docker ps | grep federation-service | awk '{print $1}'` | grep id_token