Include app-specific information in a custom claim

If you want to include certain app-specific information in a token claim, you can do so by first adding the metadata into the profile section of the app. You can access any values that are put inside the app profile using app.profile written in Okta Expression Language.

To include, for example, the app label parameter in a token claim:

• Create an app with the Profile object.
• Add a custom claim to your Custom Authorization Server.

Note: You can directly use both app.id and app.clientId as claims.

Create an app with the Profile object

Create an app with the Profile object using the Apps API.

{
      "name": "oidc_client",
      "label": "Example App",
      "signOnMode": "OPENID_CONNECT",
      "credentials": {
        "oauthClient": {
          "token_endpoint_auth_method": "client_secret_post"
        }
      },
      "profile": {
        "label": "Example App"
        },
      "settings": {
        "oauthClient": {
          "client_uri": null,
          "logo_uri": null,
          "response_types": [
            "token"
          ],
          "grant_types": [
            "client_credentials"
          ],
          "application_type": "service",
          "consent_method": "REQUIRED",
          "issuer_mode": "ORG_URL"
        }
      }
    }

Add a custom claim

Note: You can only add custom claims to a Custom Authorization Server, not the Org Authorization Server. See Authorization Servers for more information on the types of authorization servers available to you and what you can use them for.

To add a custom claim:

1. In the Developer Console, navigate to API, and then Authorization Servers.

2. Select the name of the Custom Authorization Server where you want to add the claim, and then click Claims.

3. Click Add Claim, and then configure the claim settings:

   Note: For more information on these fields, see Add a custom claim to a token.

   • Name — Enter a name for the claim, such as applabel.

   • Include in token type — Leave the default of Access Token.

   • Value type — Leave the default of Expression to define the claim by an Expression written in Okta Expression Language.

   • Value — This option appears if you chose Expression. For this example, enter app.profile.label, which is referencing the app Profile attribute that you want to include in the claim.

   Note: You can validate that your expression returns the results expected using the Token Preview tab.

   • Disable claim — Leave this clear for this example.

   • Include in — Leave Any scope selected for this example.

4. Click Create.

5. (Optional) Confirm that your custom claim was successfully added by retrieving a list of all claims from your authorization server, including the custom claims, using the /claims endpoint. See Verify the custom claim.

Request a token that contains the custom claim

In this example, the service application's token_endpoint_auth_method was set to client_secret_post when we created the app above. Include both the client_id and the client_secret values as additional parameters in the POST request body to your Custom Authorization Server's /token endpoint. For the specific steps on building the request URL, receiving the response, and decoding the JWT, see Request a token that contains a custom claim.

curl -v -X POST \
-H "Content-type:application/x-www-form-urlencoded" \
"https://${yourOktaDomain}/oauth2/default/v1/token" \
-d "client_id={client_id}&client_secret={client_secret}&grant_type=client_credentials&scope=aCustomScope"

If the credentials are valid, the access token is sent in the response:

{
    "access_token": "eyJhbG[...]1LQ",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "aCustomScope"
}

Next Steps