It is possible to incorporate app-specific information into custom claims within tokens by utilizing the App Profile object. Application attributes can be added to the profile for the application itself (not for the assigned user), either in the UI or via the Apps Application Programming Interface (API). Once created, these attributes can then be referenced in a Custom Claim in an expression by using app.profile.<attribute_name>.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Application Programming Interface (API)
• OpenID Connect (OIDC) / OAuth 2.0 Applications
• Custom Claims
• Okta Expression Language

How are the App-Specific Token Claims configured?

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

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

Step 1: Add Custom Attributes to the Application Profile Object

To include specific app information in a token claim, the metadata must be added to the profile object of the app. Configuring this can be achieved for a new or existing application, either by using the Okta Apps API endpoint or by configuring it in the Okta Admin Console.

• Option A: Add Custom Attribute in the Okta Admin Console
  1. In the Okta Admin Console, go to Applications and Resources and select Applications.
  2. Select the application.
  3. Go to the General tab and scroll to the Application profile attributes section.
  4. Select Edit and configure the application attributes within a JSON object.

Example:

{
  "label": "Test App"
}

• Option B: Add a Custom Attribute Using the Apps API Endpoint
  • Refer to the Solution in the following article for complete steps: How to Get OIDC/OAuth Application Attributes as Claims in id_token/access Token | Okta Support Center.
  • For more information about using the Apps API endpoint, please refer to Create an Application and look at the details for the profile object.

Step 2: Create a Claim 

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.

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

Create or update an OIDC application with the profile object, create a custom claim in the authorization server, and use the Okta Expression Language to access the attributes.

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