Map Attributes From an External OpenID Connect Identity Provider Into the Okta User Profile
Last Updated:
Overview
When users authenticate into Okta through a custom OpenID Connect (OIDC) Identity Provider (IdP), custom or non-standard attributes remain unavailable until Okta maps them. To receive these attributes, add them to the IdP user profile and configure profile mappings from the IdP user profile into the Okta user profile.
Applies To
- Okta Identity Engine (OIE)
- Okta Classic Engine
- OpenID Connect (OIDC) Identity Provider
Cause
When users authenticate into Okta through a custom OIDC IdP, any custom or non-standard attributes originating from the IdP remain unavailable within Okta until Okta is configured to explicitly map them.
Solution
How are custom attributes mapped from an OIDC IdP to Okta?
To receive custom or non-standard attributes from the user profile within the IdP into Okta, add the attributes to the IdP user profile. Then, configure profile mappings from this IdP user profile into the Okta user profile. Once the attribute is available within the Okta user profile, Okta can map it to other applications within the Okta org as needed.
The Criteria for Mapping OIDC Claims Depend on the Userinfo Endpoint and ID Token Payload
When using an OIDC IdP, Okta looks for user attributes in the response from the Userinfo endpoint or within the ID Token payload. If the IdP configuration includes a Userinfo endpoint, Okta checks only for user attributes in the response, not the ID Token. If the configuration omits a Userinfo endpoint, Okta relies on the ID Token payload instead.
The OIDC IdP must meet one of the following criteria for this mapping to be possible:
- The claim is present in the ID Token, and the IdP lacks a configured Userinfo endpoint.
- The claim is present in the Userinfo response, and the IdP has a configured Userinfo endpoint.
- The claim is present in both the ID Token and the Userinfo endpoint.
If the setup matches one of the options above, add an attribute to the IdP user profile with its external name set to the same value as the name of the claim present in the ID Token or Userinfo response. Then, map the attribute from the IdP user profile into the Okta user profile. Once it is within the Okta user profile, the attribute is accessible in application user profiles or in a custom claim.
Add the custom attribute to the IdP profile, add a matching attribute to the Okta profile, and configure the mapping between the two profiles.
- In the Profile Editor, navigate to the profile for the OIDC IdP and click Add Attribute to add a new custom attribute with its External name set to the claim name (for example,
favorite_ice_cream).
- In Profile Editor, navigate to the Okta Profile, and click Add Attribute to add a matching custom attribute.
- Configure a mapping from the IdP user profile to the Okta user profile so that Okta maps the value over.
From here, Okta can map this value from the Okta user profile into an application user profile or into a custom claim using user.<variable_name>.
NOTE: For Okta to update these attributes on both user creation and update, configure the Identity Provider as a Profile Source.
