About Modifying Authentication Context

Extensions that happen after users are authenticated with their identity source are used to enhance the authentication context of the authenticated entity. Such enriched authentication context can be later on used to populate claims in tokens minted by the Cloudentity platform.

Extensions that are placed post identity source authentication can be used:

• To pull data (such as, for example, user permissions) from an external system

• To overwrite static attributes in the authentication context

• To enhance authentication context with risk information from external services

• Enhance authentication context with business information for the user from external services (like subscription or licensing)

• Enhance authentication context with static attributes, for example, to dynamically set the AMR and ACR Claims for Open Banking

• Transform identity claims from identity provider using various functions

Learn more

You can learn more about Cloudentity Extensions and enhancing authentication context by reading the Extending Cloudentity Capabilities article.

Available Inputs

When creating Extension scripts that enhance authentication context post user authentication, the developers can use the following input objects:

• authn_context - to enhance or modify the authentication context for an authenticated entity

• amr - to be able to dynamically set the value for the Authentication Method Reference (AMR) claim

• acr - to be able to dynamically set the value for the Authentication Context Class Reference (ACR) claim.

• idp_sub - to be able to set the identity source subject claim, for example, when the hashed subject format is used.

Tip

You can see the available input example in the Extensions editor:

Available Outputs

Extensions enhancing the authentication context can produce the following output:

• authn_context - to show the results of enhancing the authentication context

• amr - to show the results of setting the value of the amr attribute.

• acr - to show the results of setting the value of the acr attribute.

Example Output

{
  "acr": "1",
  "amr": [
    "pwd"
  ],
  "authn_ctx": {
    "email": "jdoe@example.com",
    "email_verified": true,
    "family_name": "Doe",
    "given_name": "John",
    "idp_sub": "user",
    "name": "John Doe",
    "sub": "9a663bf966861677ca77004a6b4c1fc87d11d78afeb245fb3549ab32783af3ab"
  },
  "email_verified": true,
  "idp_sub": "user"
}

Enhance Authentication Context

1. Create your Extension.

   When creating the Extension, use available inputs, outputs, and dependencies.

   Creating Extensions

   For instructions on how to create Cloudentity Extensions, test using test mode, and to learn what are recommended best practices when working with Extensions, see the Creating and Testing Extensions How-to article.

   To check how Extensions enhancing authentication context work and look, see the Sample Script section.

2. Go to Identity Providers, select an IDP of your choice, and assign the Extension in Mappings > Post authentication Extension.

   

3. Verify enhanced authentication context using Sandbox IDP and Demo Application/API

Sample Script

module.exports = async function(context) {
const request = require('request-promise-native');
try {
  const response = await request({
    method: 'GET',
    json: true,
    uri: 'http://example.com/resource/path'
  });

  return {
      authn_ctx: {
        authorized_clients: response.find(x => x.userId == context.authn_ctx.given_name).authorizedClients.map(x => x.name),
        static_attribute: 'static_value'
      }
    };
}
catch(e) {
  console.error(e);
}
}

The above script compares the given_name in the authentication context against the userId in the target JSON record. When they match, the script writes the underlying authorizedClients.name parameter into the authorized_clients authentication context object. Additionally, the script sets the static_attribute in the authentication context to static_value. Cloudentity can, therefore, issue claims mapped to the modified authorized_clients and static_attribute attributes.

Verify Enhanced Authentication Context

To illustrate how to verify enhanced authentication context, we will use Cloudentity Sandbox IDP, Demo Application, and the sample script from the section above.

Prerequisites

1. Sandbox IDP and Demo Application available for the workspace.

2. Authentication context is defined.

   For testing purposes, add authorized_clients (list of strings) and static_attribute (string) to your authentication context.

3. Claims to be issued are mapped to authentication context attributes affected by your script.

   For testing purposes, make sure that authorized_clients and static_attribute are issued as claims in the Demo Application.

4. Sample Script added for Extensions within the workspace.

Test Extension with Sandbox IDP and Demo Application

1. Enable the script in the Sandbox IDP. Go to Identity Data > Identities > Sandbox IDP -> Mappings and select the script from the Post authentication script list.

2. In Identity Data > Identities > Sandbox IDP > Mappings, map the name IDP attribute to the given_name context attribute.

3. Add authorizedClients (list of strings) and static_attribute (string) to your authentication context.

4. Add the authorizedClients and static_attribute claims to your workspace. Map them to the corresponding attributes defined in the previous step. Assign the profile scope to both claims. For more information, see Configuring claims for ID tokens and access tokens.

5. To simulate external data, add the following object to an online sharing tool (such as Hastebin or similar):

   Note

   Make sure that userId matches an existing user name in the Sandbox IDP user pool.

   [
     {
         "userId":"SANDBOX_USER_NAME",
         "partnerDetails":{
           "orgId":"001",
           "partnerId":"001",
           "partnerType":[
               "third-party-access"
           ]
         },
         "authorizedClients":[
           {
               "name":"Client 1",
               "privileges":[
                 "tpa-access"
               ]
           },
           {
               "name":"Client 2",
               "privileges":[
                 "tpa-access"
               ]
           },
           {
               "name":"Client 2",
               "privileges":[
                 "tpa-access"
               ]
           },
           {
               "name":"Client 4",
               "privileges":[
                 "tpa-access"
               ]
           }
         ]
     }
   ]
   

6. Add the path to the above resource to the uri parameter in your script.

7. Log in to the Demo Application as the user you entered in the userId attribute above.

   Result

   In case of the sample script used for this test , we can expect the authorized_clients and static_attribute claims to be modified. Inspect the ID token presented after login to confirm this:

   {
   "acr": "0",
   "aid": "default",
   "amr": [
       "pwd",
       "mfa"
   ],
   "aud": "default-demo",
   "auth_time": 1633442410,
   "authorized_clients": [
       "Client 1",
       "Client 2",
       "Client 3",
       "Client 4"
   ],
   "email": "mail@domain.com",
   "exp": 1633446013,
   "given_name": "SANDBOX_USER_NAME",
   "iat": 1633442413,
   "idp": "c5dh64n3qv46ahmfntq0",
   "iss": "https://tenant.authz.cloudentity.io/tenant/default",
   "jti": "88c8cb95-a826-41c1-8e55-c2508745d593",
   "name": "Joe",
   "nbf": 1633442413,
   "nonce": "c5e5klpli7m52gnpk300",
   "rat": 1633442413,
   "scp": [
       "email",
       "openid",
       "profile"
   ],
   "static_attribute": "static_value",
   "st": "public",
   "sub": "12539980",
   "tid": "cloudentity-tenant"
   }