Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

Client application configuration

Identity providers

search

Identity providers

The OneWelcome Identity Platform depends on an identity provider (IDP) to identify a user and supports multiple integrations with identity providers. Custom integrations are also supported.

To configure identity providers, in the administration console, go to Configuration and then to Identity providers.

General configuration

Add IDP

You can set the following properties for each type of identity provider:

  • Type is the type of this identity provider. After you set the type, you can change the type only from a generic SAML to a Consumer Identity Manager (CIM) identity provider.

  • Identifier is the ID that uniquely identifies the IDP. You cannot change it later.

  • Name is a human-readable name for the identity provider. This name is shown only to administrators, and is not shown to users.

  • Default is the default identity provider that is assigned to an application when no identity provider is specified.

  • Enabled is a flag to enable or disable this identity provider.

Additionally, for those identity providers that expose identities using an API, it is possible make the OneWelcome Identity Platform aware of this API. See Configure user information endpoint.

Configure a SAML identity provider

Add saml IDP

To use the SAML IDP integration, ensure that the SAML Service Provider enabled setting is enabled.

When you use the SAML IDP functionality, the OneWelcome Identity Platform acts as a SAML service provider. You can configure the service provider metadata using the SAML service provider configuration. In the SAML IDP, configure the OneWelcome Identity Platform as a service provider. For more information, see configuring the metadata of the SAML service provider.

You must configure the Entity ID for the SAML IDP in the OneWelcome Identity Platform. The Entity ID in the OneWelcome Identity Platform configuration corresponds to the Entity ID in the IDP metadata.

There are two options for specifying the IDP metadata:

  1. Dynamic via URI: The metadata is automatically fetched from the provided URL, which is typically the SAML IDP. This is the preferred option because any refresh of the metadata is handled automatically.

  2. Static XML: The complete XML representing the SAML metadata is provided as static text. When using this option, make sure that the expiry date is sufficient and the keys within the metadata are up-to-date.

To ensure that migration to a new certificate runs smoothly, the OneWelcome Identity Platform supports multiple certificates in the metadata.

The OneWelcome Identity Platform supports IDP-initiated SAML single logout (SLO). By enabling SLO, the IDP is able to terminate sessions at the OneWelcome Identity Platform. This means that when a user logs out at the identity provider, the OneWelcome Identity Platform receives a request to revoke all access tokens and grants associated with that session. This feature is available only for web clients that do not use refresh tokens.

The OneWelcome Identity Platform can choose the requested authentication-context class reference, which is then used with all SAML requests. If none is specified it defaults to urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport

The SAML authentication context comparison tells the identity provider how to compare the requested authentication context to supported authentications.

Note

The SLO enabled check box is available in the form only if the SLO enabled SAML Service Provider Configuration option is enabled.

By default, only the user ID is mapped based on the name ID that is available in the SAML assertion. By adding an attribute mapping, you can use more user attributes from the SAML assertion. When creating an attribute mapping, both the Name and FriendlyName of a SAML attribute can be used.

SAML attribute mapping

To enable assertion attribute mapping, you must enable the Map assertion attributes option on the SAML IDP configuration page. This feature enables mapping all attributes in the SAML assertion from the external IDP to claims (1:1) in the ID token and UserInfo.

The attribute mapping functionality allows you to restrict this mapping to specific claims. If you have enabled the UserInfo integration, any assertion attributes that have the same name are overwritten.

The OneWelcome Identity Platform supports free format attribute names. All attributes (including the non-default attributes) are available in the token introspection response and in the consent template. A set of default attributes is available that can lead to different behavior in the OneWelcome Identity Platform:

  • userId
  • authenticationLevel
  • firstName
  • lastName
  • email
  • phoneNumber
  • languageCode

Configure an OAuth identity provider

Add OAuth IDP

The OneWelcome Identity Platform can act as an OAuth client for an identity provider that acts as an OAuth authorization server. The OneWelcome Identity Platform then uses the OAuth authorization code flow to obtain an access token and uses that access token to get user information.

The following properties can or must be set for the OAuth identity provider:

Property Example Required Description
Client ID jeguighreuwih8792459uht893 Yes The identifier for the OneWelcome Identity Platform in the OAuth IDP
Secret fjerfr9uf089rf908f90refeef Yes The secret for the OneWelcome Identity Platform in the OAuth IDP
Authorization URL https://example.com/oauth/authorize Yes The URL to start the authorization without request parameters. These are added by the OneWelcome Identity Platform.
Token URL https://example.com/oauth/token Yes The URL to exchange the access grant for an access token without request parameters. These are added by the OneWelcome Identity Platform. The URL is called using HTTP POST. The client ID and secret are sent using the HTTP authorization header (basic authentication) or the URL-encoded form.
Profile URL https://example.com/me Yes The URL for an OAuth resource call that returns a user profile. The URL is called using HTTP POST. The access token is sent using the HTTP authorization header with a bearer token.
Scopes profile No Scopes that are needed for getting the user profile. Multiple scopes must be separated by a space. An empty value is allowed.
Map assertion attributes True No

During the OAuth authorization flow, the user is redirected back from the OAuth IDP to the OneWelcome Identity Platform. This redirect URL is the engine base URI + the engine context root + /oauth-idp/callback. For example: https://token-server.example.com/oauth/oauth-idp/callback.

Attribute mappings are not supported in this IDP. The OneWelcome Identity Platform expects the profile in the following structure to extract the user identifier:

{
  "userId": "user-1234"
}

Configure a custom API identity provider

Custom API identity providers can be either One Step or Two Step. These identity providers use the OneWelcome Identity Platform extension engine to execute custom JavaScript to validate the registration. Scripts should be supplied when configuring this identity provider:

  • Two Step requires an Init registration and Complete registration script.

  • One Step requires only a Complete registration script.

Both can have an optional script for Backchannel communication, but that is not required.

Add custom API IDP

For more information about the identity provider, see custom registration.

For help creating the scripts, see the example scripts.

Configure user info endpoint

For any type of identity provider, it is possible to configure an endpoint that the OneWelcome Identity Platform can use as a source of user identity attributes. It is used by the OneWelcome Identity Platform to expose UserInfo and populate ID tokens with claims in OpenID Connect flows. This endpoint needs to be compliant with the person API.

  • Enabled indicates whether identity attributes can be retrieved with an API.
  • Identity source URL is the URL of the person API-compliant endpoint
  • Username that is used when accessing the API.
  • Password that is used when accessing the API.

The calls to the API are cached. You can configure the time-to-live (TTL) of this cache in the administration console.

Attribute mapping

Add attribute mapping

Identity provider attributes

Some identity providers are capable of providing user attributes during authorization. These attributes are associated with respective access tokens and are available as a key-value pair for an inspection using the token introspection API.

By default, the attributes are stored under the original keys, but it is possible to define a custom mapping that overrides that behavior. If at least one custom mapping is defined, only those attributes are mapped. That means other attributes that are not mapped are dropped. If you are using SAML attribute name mapping in the OneWelcome Identity Platform CIM, ensure that you coordinate the configuration between the two products. The attribute names are case-sensitive.

A special user attribute is the user identifier. It identifies the user within the OneWelcome Identity Platform. For a SAML-based identity provider, the assertion Subject/NameID is the standard user identifier. To use a different attribute as the user identifier, create an attribute that maps to userId.

Person API attributes

The attributes are stored during authorization, but the OneWelcome Identity Platform does not resynchronize them later. This results in potentially stale data. To overcome this limitation, consider leveraging the person API integration.

If the person API integration is enabled, the token introspection API returns all non-empty attributes from the person API, in addition to the attributes that are returned during the authorization.

The following attributes are supported:

  • first_name
  • last_name
  • gender
  • birth_date
  • locale
  • email
  • email_verified
  • phone_number
  • phone_number_verified
  • street_name
  • house_number
  • house_number_addition
  • city
  • region
  • country
  • postal_code

Similar to attributes provided by an identity provider, the names of attributes as returned by the token Introspection API can be changed by defining a custom mapping. If at least one custom mapping is defined, only those attributes that are configured are mapped. The attribute names are case-sensitive.

On this page