Administrators often need to include custom user profile attributes as claims within OpenID Connect (OIDC) tokens to pass additional user data to downstream applications. Achieve this goal by creating the custom attribute, mapping it to the application profile, and configuring the authorization server to include the attribute in the token payload.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• OpenID Connect (OIDC) Applications
• Custom Claims

How are custom attributes mapped to the application profile?

Create the custom attribute in the Okta user profile and map it to the application user profile to ensure the data is available for the token.

1. Navigate to Directory, and then select Profile Editor.
2. Ensure the custom attribute exists in both the Okta user profile and the application user profile.
3. Select Mappings to create a mapping from the Okta user profile to the application user profile for the custom attribute.

Review the following configuration to verify the profile mapping from Okta to the application.

 (Verify the custom attribute contains a value for the specific user before proceeding).

How is the custom claim configured in a Custom Authorization Server?

If using a Custom Authorization Server to mint the token, create a custom claim to evaluate the mapped attribute and inject it into the token. (Skip this step if using the built-in Org Authorization Server).

1. Navigate to Security, select API, and then select Authorization Servers.
2. Select the desired Custom Authorization Server and navigate to the Claims tab.
3. Create a custom claim and provide an expression in the Value field.
4. Choose the token type (ID Token or Access Token) that should include this custom attribute.

Review the following configuration to verify the custom claim settings.

How is the custom claim requested during authorization?

Include the appropriate scopes in the authorization request to ensure the authorization server returns the custom claims.

• Include the profile scope in the /authorize or /token requests.

NOTE: Review the following behaviors regarding tokens and custom attributes:

• When requesting both the ID token and Access token, Okta returns a "thin" ID token. Send the Access token to the Userinfo endpoint to retrieve the full list of claims. For more details, refer to Okta Groups or Attribute Missing from ID Token.
• Custom attributes of a user profile are available in the Userinfo endpoint only when using the built-in Org Authorization Server.
• Custom attributes are not available in the Userinfo endpoint when using a Custom Authorization Server. If using a Custom Authorization Server, include them as custom claims to access the user profile attributes.

Related References

• Custom Authorization Server
• Org Authorization Server
• Okta Groups or Attribute Missing from ID Token
• Userinfo