Mapping eID claims to Auth0: Using Actions and Rules

Through our partnership with Auth0, Criipto offers a range of eID services to help Auth0 customers streamline identity verification and improve user experience by letting users log in with their national eID.

In a previous blog post, we showed how easy it is to connect an Auth0 application with Norwegian BankID via Criipto. But it’s just as easy to add every other eID we support into an existing Auth0 application. All it takes is adding a new Enterprise Connection with slightly varying configurations.

Let’s look at mapping Criipto claims to Auth0 in more detail. This can be done using two different methods: Auth0 Rules or Auth0 Actions.

The first, more straightforward approach, involves adding a custom claim using a Rule.

Using Actions, on the other hand, requires a few more configurations and the use of Auth0 Management API.

By the end of this guide, you’ll have a better understanding of how to configure the integration between Criipto and Auth0 to meet your needs and access all the required user data.

To follow along, you‘ll need an Auth0 application with an OpenID Connect Enterprise Connection for the eID of your choice. (This guide should help if you’d like to get started.) 

1. Adding a custom claim with Auth0 Rules

Adding a new Rule

This method involves adding a Rule to the Login flow of your Auth0 application.

In the Rule, we’ll define the logic that adds a custom claim to the ID token generated by Auth0 upon a successful user login. When a user logs in with their eID, the information from the Identity Provider will be included in their Auth0 User Profile.

We’ll show code examples for including Social Security Numbers from various European eIDs, as well as company CVR numbers for the Danish MitID Erhverv (MitID Business), in a custom claim. You can add other custom claims from external Identity Providers in the same way.

In Criipto implementation, every national eID has a unique JWT key for a Social Security Number, summarized in the table below:

For more information on each eID, including full JWT content, please refer to our documentation.

Adding a New Auth0 Rule

1. In Auth0, from the main menu, choose Auth Pipeline, then Rules.
2. Create a new rule using the Empty rule template.
3. Choose a name for the Rule (e.g. “Add SSN to ID Token”), then add a script for the eID of your choice. See code snippets below (“https://example.com” is a placeholder for your own namespace).
4. After adding the script, click Save Changes.
5. Make sure the Rule is enabled for your Login flow. You can check this in Actions > Flows > Login, or by checking that the Rule toggle is enabled.
   
   

Code snippets

Danish MitID

This example only maps the user's SSN. You can see the full list of Danish MitID claims here.

function (user, context, callback) {
  context.idToken['https://example.com/cprNumberIdentifier'] = user.cprNumberIdentifier;
  return callback(null, user, context);
 }

Danish MitID Erhverv (MitID Business)

This example maps the user's SSN and the CVR number of the company the user is affiliated with. You can see the full list of Danish MitID Erhverv claims here.

function (user, context, callback) {
 context.idToken['https://example.com/cprNumberIdentifier'] = user.cprNumberIdentifier;
 context.idToken['https://example.com/cvrNumberIdentifier'] = user.cvrNumberIdentifier;
 return callback(null, user, context);
}

Swedish BankID

This example only maps the user's SSN. You can see the full list of Swedish BankID claims here.

function (user, context, callback) {
 context.idToken['https://example.com/ssn'] = user.ssn;
 return callback(null, user, context);
}

Norwegian BankID

This example only maps the user's SSN. You can see the full list of Norwegian BankID claims here. (Please note that for Norwegian BankID, additional user data requires explicit user consent.)

function (user, context, callback) {
 context.idToken['https://example.com/socialno'] = user.socialno;
 return callback(null, user, context);
}

Finnish Trust Network

This example only maps the user's SSN. You can see the full list of Finnish Trust Network claims here.

function (user, context, callback) {
 context.idToken['https://example.com/hetu'] = user.hetu;
 return callback(null, user, context);
}

ItsMe

This example only maps the user's SSN. You can see the full list of ItsMe claims here.

function (user, context, callback) {
 context.idToken['https://example.com/nationalnumber'] = user.nationalnumber;
 return callback(null, user, context);
}

That’s all it takes. Whenever the Social Security Number (of a company CVR number) is available through a national eID via Criipto, it will be added to the Auth0 ID token (as long as the Rule is enabled).

2. Adding a custom claim with Auth0 actions

Actions offer more flexibility than Rules, and are the recommended way to add custom claims to access and ID tokens.

But at the moment, Auth0 Actions have a limitation of not exposing user data from external Identity Providers. You currently cannot access the claims added by Identity Providers in the Actions code, so you’ll need to work around this limitation.

The only workaround we found is to integrate a custom Action with the Management API to look up the User Profile. We’ll explain the steps below, so you can pick the implementation that works best for you. Please be aware that Auth0 Management API has rate limits at high usage (see the above link to Action Limitations).

Configuring Management API and creating a custom Action

We’ll use this walkthrough to add the Management API to our Action code. We will use the Management API client to access the User Profile and retrieve the necessary data. (In our case, the user’s Social Security Number available in JWT claims provided by Criipto.)

1. To configure the Management API, create and authorize a Machine to Machine Application for the Action.
2. Authorize it to use the Management API with the required scopes. We'll need Read:users and update:users. 

3. From the Actions tab, create a new custom Action with the Login / Post Login trigger.

4. Store the application’s credentials in the Action’s event.secrets object. You can find the domain, client ID, and client secret in the Settings tab of the Machine to Machine Application created in Step 1.

5. Add the auth0 npm module.

6. Add your Action code. Initialize and use the Management API client in the Action to access the User Profile. Then add a custom claim.

As with Rules, your Action code may differ slightly depending on the eID you’re retrieving the data from. The code snippets below show how to add a custom Social Security Number claim available via a national eID through Criipto. For Danish MitID and Norwegian BankID, we’ll also add a custom claim containing the user's address.

Danish MitID

const ManagementClient = require('auth0').ManagementClient;

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://example.com';
  const management = new ManagementClient({
    domain: event.secrets.AUTH0_DOMAIN,
    clientId: event.secrets.AUTH0_MANAGEMENT_CLIENT_ID,
    clientSecret: event.secrets.AUTH0_MANAGEMENT_CLIENT_SECRET,
    scope: 'read:users update:users',
  });
  const user = await management.getUser({ id: event.user.user_id });

  api.idToken.setCustomClaim(`${namespace}/address`, user.address);
  api.idToken.setCustomClaim(`${namespace}/cprNumberIdentifier`, user.cprNumberIdentifier);
};

* For Danish MitID, it is possible to purchase an add-on to look up legal, verified addresses for Danish citizens. 

Danish MitID Erhverv (MitID Business)

const ManagementClient = require('auth0').ManagementClient;

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://example.com';
  const management = new ManagementClient({
    domain: event.secrets.AUTH0_DOMAIN,
    clientId: event.secrets.AUTH0_MANAGEMENT_CLIENT_ID,
    clientSecret: event.secrets.AUTH0_MANAGEMENT_CLIENT_SECRET,
    scope: 'read:users update:users',
  });
  const user = await management.getUser({ id: event.user.user_id });

  api.idToken.setCustomClaim(`${namespace}/cprNumberIdentifier`, user.cprNumberIdentifier);
  // Danish Business Registry Number (CVR Nummer)
  api.idToken.setCustomClaim(`${namespace}/cvrNumberIdentifier`, user.cvrNumberIdentifier);
};

* For Danish MitID Erhverv, the company CVR number will be available in the JWT claims. 

Swedish BankID

const ManagementClient = require('auth0').ManagementClient;

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://example.com';
  const management = new ManagementClient({
    domain: event.secrets.AUTH0_DOMAIN,
    clientId: event.secrets.AUTH0_MANAGEMENT_CLIENT_ID,
    clientSecret: event.secrets.AUTH0_MANAGEMENT_CLIENT_SECRET,
    scope: 'read:users update:users',
  });
  const user = await management.getUser({ id: event.user.user_id });

  api.idToken.setCustomClaim(`${namespace}/ssn`, user.ssn);
};

Norwegian BankID

const ManagementClient = require('auth0').ManagementClient;

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://example.com/';
  const management = new ManagementClient({
    domain: event.secrets.AUTH0_DOMAIN,
    clientId: event.secrets.AUTH0_MANAGEMENT_CLIENT_ID,
    clientSecret: event.secrets.AUTH0_MANAGEMENT_CLIENT_SECRET,
    scope: 'read:users update:users',
  });
  const user = await management.getUser({ id: event.user.user_id });

  api.idToken.setCustomClaim(`${namespace}/address`, user.address);
  api.idToken.setCustomClaim(`${namespace}/socialno`, user.socialno);
};

* For Norwegian BankID, unverified address information is available by request as long as the user has provided explicit consent.

Finnish Trust Network

const ManagementClient = require('auth0').ManagementClient;

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://example.com/';
  const management = new ManagementClient({
    domain: event.secrets.AUTH0_DOMAIN,
    clientId: event.secrets.AUTH0_MANAGEMENT_CLIENT_ID,
    clientSecret: event.secrets.AUTH0_MANAGEMENT_CLIENT_SECRET,
    scope: 'read:users update:users',
  });
  const user = await management.getUser({ id: event.user.user_id });

  api.idToken.setCustomClaim(`${namespace}/hetu`, user.hetu);
};

ItsMe

const ManagementClient = require('auth0').ManagementClient;

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://example.com/';
  const management = new ManagementClient({
    domain: event.secrets.AUTH0_DOMAIN,
    clientId: event.secrets.AUTH0_MANAGEMENT_CLIENT_ID,
    clientSecret: event.secrets.AUTH0_MANAGEMENT_CLIENT_SECRET,
    scope: 'read:users update:users',
  });
  const user = await management.getUser({ id: event.user.user_id });

  api.idToken.setCustomClaim(`${namespace}/nationalnumber`, user.nationalnumber);
};

Multiple eIDs in one action

const ManagementClient = require('auth0').ManagementClient;

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://example.com/';
  const management = new ManagementClient({
    domain: event.secrets.AUTH0_DOMAIN,
    clientId: event.secrets.AUTH0_MANAGEMENT_CLIENT_ID,
    clientSecret: event.secrets.AUTH0_MANAGEMENT_CLIENT_SECRET,
    scope: 'read:users update:users',
  });
  const user = await management.getUser({ id: event.user.user_id });

  // Danish MitID
  api.idToken.setCustomClaim(`${namespace}/cprNumberIdentifier`, user.cprNumberIdentifier);
  // Swedish BankID
  api.idToken.setCustomClaim(`${namespace}/ssn`, user.ssn);
  // Finnish Trust Network
  api.idToken.setCustomClaim(`${namespace}/hetu`, user.hetu);
};

After saving and deploying the Action, add it to the Login flow. The user’s Social Security Number will now be available in the ID token generated by Auth0 upon successful authentication.

{
 "https://example.com/cprNumberIdentifier": "2511221865",
 "nickname": "Severin Poulsen",
 "name": "Severin Poulsen",
 "birthdate": "1922-11-25",
 "iat": 1682322427,
 "exp": 1682358427
}