Skip to main content

Enhancing Authentication Context Using Cloudentity Extensions

You can define your own extension scripts in order to enhance the authentication context after the user authenticates themselves to authorize the client application. Complementary to the scripts, you can also create secrets in order to use them within scripts or to validate policies.

Enhance Authentication Context

  1. Create your Extension.

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

    Tip

    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 modifying the login flow for end users work and look, see the Sample Script section.

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

    Assigning 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);
}
}

Attribute

Description

context

Represents the entire function input. Always contains the authn_ctx and secrets objects.

authn_ctx

Your main object of interest. This object represents the authentication context and is always passed as the function input. Refer to it via context.authn_ctx.ATTRIBUTE_NAME. All attribute values written into authn_ctx by your script replace the values from the original authentication context. Attribute to be overwritten must be defined in the Cloudentity authentication context - you cannot create new attributes using the script. Please check the authentication context definition in your Cloudentity workspace if you're not sure which attributes are defined.

Note that attributes returned by the script do not need to be mapped to the authentication context in Cloudentity.

secrets

This object represents Cloudentity secrets. Refer to it via context.secrets.SECRET_NAME. You can find secret names in the Secrets section.

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.

    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"
}

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 input example

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"
}
In this section: