User claims and attributes

This section explains how the OneWelcome Identity Platform deals with user claims and attributes during the most commonly used flows.

Authorization

1 The OAuth Client or OIDC relying party initiates the authorization code flow.

2 Based on the client_id parameter (optionally also idp_id), the OneWelcome Identity Platform resolves the IdentityProvider instance that is used for user authentication.

2.1 If the underlying IdentityProvider is of type OIDC, the OneWelcome Identity Platform redirects the user to the defined OIDC provider with another authorization request.

2.1.1 When authenticated, the OIDC provider redirects back to the OneWelcome Identity Platform with the authorization code. the 1.OneWelcome Identity Platform exchanges the code for the AccessToken and IDToken pair. The IDToken is the primary source of information about the user. An internal user object is created and populated with all the user claims available in the ID token. In addition to the user attributes, the AMR and ACR claims are also stored in the user object. If the identity provider is of type Tulip, the OneWelcome Identity Platform only reads the AMR and ACR claims from the ID token.

2.1.2 If the IdentityProvider is of type Tulip, it is likely that a User Data Enhancer (UDH) API integration is configured. If this is the case, the user claims are requested using another API call from UDH. The OneWelcome Identity Platform passes the user identifier (subject) and a set of scopes requested by the client. Otherwise, the user object is persisted.

2.1.3 The UDH response is mapped to a UserInfo standard format.

2.1.4 The user object is populated with any claims returned by the UDH service.

2.2 If the underlying IdentityProvider is of type SAML, the OneWelcome Identity Platform redirects the user to the defined SAML identity provider with SAML AuthnRequest (whether it is a redirect or a POST call depends on the integration characteristic).

2.2.1 the OneWelcome Identity Platform processes the SAML AuthnResponse. SAML attribute mapping is triggered if any are defined for a specific SAML identity provider. If no mappings are available, all SAML assertion attributes are used in the next step.

2.2.2 SAML assertion attributes are mapped to claims according to the configuration. Any unmapped attributes are discarded or filtered out.

2.2.3 An internal user object is created and populated with all user claims provided by the SAML assertion. The AMR or ACR value is also stored in the user object.

3 The user object with all the claims is persisted.

4 The authorization request is considered successful, and the OneWelcome Identity Platform generates the authorization_code.

5 The OAuth client or OIDC relying party receives a 302 Redirect with the authorization_code from the OneWelcome Identity Platform.

Token

1 The OAuth client or OIDC relying party requests the exchange of the authorization_code for an access token or ID token.

2 The OneWelcome Identity Platform resolves a user object that was persisted during the authorization code flow.

3 If an access token customization web hook is configured for a requesting OAuth client or OIDC relying party, see #3.1.

3.1 Retrieve the user claim from the underlying identity provider. Depending on the type of identity provider, different sources may be considered. If the user claims were fetched during the authorization code flow, the OneWelcome Identity Platform resolves them from an internal cache.

3.2 The user object is populated with any claims returned by the user info API. If a specific claim already exists in the user object, it is overwritten with the claim from the user info source, which is considered more recent.

3.3 The access token customization web hook is executed. The hook implementation is provided with all available user information, as well as contextual details about the access token being created.

4 If the requesting client is of type OIDC and the openid scope was requested, the OneWelcome Identity Platform triggers the ID Token assembly, see #4.1.

4.1 The OneWelcome Identity Platform starts to assemble all the details needed to generate the ID token, using the internal user object as the source of the user information.

4.2 Retrieve user claims from the underlying identity provider if available, otherwise see #4.2.6.

4.2.1 Retrieve user claims from the underlying identity provider. Depending on the type of identity provider, different sources may be considered. If the user claims were fetched during the authorization code flow, the OneWelcome Identity Platform resolves them from an internal cache.

4.2.2 Check if the underlying identity provider is of type OIDC, otherwise see #4.2.3.

4.2.3 Check if the underlying identity provider is of type SAML, otherwise see #4.2.6.

4.2.4 Check if the Map Assertion Attributes toggle is enabled for underlying SAML identity providers, otherwise see #4.2.6.

4.2.5 The user object is populated with all claims returned by the user info API. If a specific claim already exists in the user object, it is overwritten with the claim from the user info source, which is considered more recent.

4.2.6 If a user details customization web hook is configured for a requesting OAuth client or OIDC relying party, proceed to #5.

4.2.7 The user details customization web hook is executed. The hook implementation is provided with all available user information, as well as contextual details about the ID token being created.

5 The OneWelcome Identity Platform generates an access token and ID token (if requested).

6 The OAuth client or OIDC relying party receives a token response from the OneWelcome Identity Platform.