This article provides a comprehensive guide on incorporating app-specific information into custom claims within tokens by utilizing the App Profile object. It details the limitations of directly including certain app-specific attributes and offers a step-by-step approach to achieve this using the Okta Apps API.

• OpenID Connect (OIDC)
• Custom Claims
• Access Token/ ID Token
• Profile Object
• Okta Apps API Endpoint
• Okta Expression Language

When including OIDC app-specific information in custom claims, only the following three attributes are available:

• app.id
• app.clientId
• app.profile

App-specific information other than the App ID and Client ID cannot be directly included in the custom claims of a token.

To include specific app information in a token claim, the metadata must be added to the profile object of the app. This can be achieved by either creating an app with the Profile object or updating an existing app by adding the Profile object using the Okta Apps API endpoint.

Please refer to Create an Application with the Profile object using the Apps API endpoint.

Once the profile object is created with custom attributes of the app information, the attributes and their values can be accessed from within the app profile using the app.profile expression of the Okta Expression Language.

Create or update an OIDC single-page application (SPA) or Web application called "Example App" along with the profile object and include necessary attributes in it using the Apps API endpoint.

Example:

app.profile.<attribute_name>

This claim expression can then be added to the custom claim by referring to Add a Custom Claim to Token.

Step-by-Step Process

1. Create or update an OIDC SPA or Web application called "Example App" along with the profile object, and include necessary attributes in it using the Apps API endpoint.
   

   {
     "name": "oidc_client",
     "label": "Example App",
     ...
     "profile": {
       "label": "Example App",
       "description": "This is an example app"
     },
     ...
   }
   

    

2. Within the custom authorization server, create a custom claim, for example, testClaim.
   • Choose the token type in which the custom claim should be included. Example - Access Token, ID Token

• • Use the following expression syntax to access the attribute you have included in the profile object.

app.profile.<attribute_name>

• • For instance, to include the application name/label from the above-created profile object in the token, the claim expression would be:

app.profile.label

• • Choose the preferred scope in which to include this custom claim.
    
    
     

Token Payload Example:

When the token is generated, the token payload will look like this:

  

NOTE:

• The token will contain the claim with the name set for the custom claim that was created, for example, testClaim and not the name set for the attribute, like label, as observed in the example above.
• For the Service or Client Credentials application, since the 'openid' and 'profile' scopes are not supported, the custom claim must be included in a custom scope, and the token type for the custom claim should be an Access Token.

Related References

• Add a custom claim to the token
• Request a token that contains the custom claim
• Creating a custom scope in the authorization server
• Add a groups claim with a static allowlist