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

Identity broker

search

Identity broker

One of the developing elements in the security landscape is the need for external identity providers (IDP) for both authentication (login) and identification (registration). This might be required by law, by your business unit, or by user expectations.

Analysts have been predicting that Bring Your Own ID (BYOID) will surpass IDs that are provided by organizations. Digital wallets are relatively new to this spectrum. Both external IDs and digital wallets have the underlying principle that the user registers at the external IDP, has both authentication and identification taken care of once, and then can use this ID to quickly access your organization.

Regulators might also demand that businesses provide users with the option of using government or bank IDs.

For prospect logins, a social ID is often used, because users initially don’t want to provide strong identification. A social ID is a quick way to create a prospect login.

Organizations using homegrown solutions often struggle to integrate with external IDPs and incorporate them into their customer journeys. The challenge is not just technical. To be compliant and to continue using the external ID, organizations need a level of maturity and must provide compliance evidence annually.

Integrations with external IDPs

Due to the growing trend to allow users to choose their authentication method, it has become complex to maintain single-sign-on for users. The provider must individually integrate and manage every integration, which is cumbersome.

By acting as an intermediary service, the identity broker connects apps with different identity providers (IDP), so that administrators don't have to integrate every IDP into their apps.

The identity broker allows you to federate to an external IDP. In the OneWelcome Identity Platform, you configure which IDPs are available for user registration and login.

Examples of these federated logins include:

  • Social IDPs: Facebook, Google, LinkedIn, X (formerly known as Twitter)

  • Known IDPs: IDIN, eHerkenning, DigiD, Itsme, FranceConnect, EU-ID, Apple, Finnish Trust Network

  • IDPs using open protocols: SAML, OpenID Connect

  • Government-issued IDs or wallets (eIDs)

  • Enterprise IDPs: Microsoft Entra ID

When federating to an external IDP, the OneWelcome Identity Platform issues and signs the token as the main IDP.

To simplify the integration task, the OneWelcome Identity Platform provides out-of-the box integrations with several external IDPs.

Federation requests

The federation request allows the identity broker to identify the purpose of an IDP configuration.

Some external IDPs support two workflows, or purposes:

  • Authentication: You might require minimal information for user logins, such as a persistent identifier.

  • Identification: You might require additional information for the on-boarding or registration journey, such as the first name, last name, address, and so on.

An IDP can have two configurations, based on the purpose. The purpose is provided in the request to the identity broker, towards the external IDP.

Just-in-time user creation

User accounts are created in the identity store with the data that is received from the external IDP when a user requests access to a protected resource or application.

For example, when a user logs in via an external IDP, the OneWelcome Identity Platform uses the information that it received from the IDP to create the user account in the identity store. If updates to the user account are allowed, then each time the user logs in via the external IDP, their data is updated in the identity store.

Configure IDPs

IDPs are responsible for the authentication (login) and identification (registration) of users.

On the OneWelcome Identity Platform console, the identity broker allows you to configure which identity providers are available for user authentication and identification. The Identity Providers page lists any IDPs that have already been configured, and includes their name, type, and status. From here, you can edit, delete, or view the details about an existing IDP, or add a new IDP.

You can add the following types of identity providers:

  • OpenID Connect (OIDC)
  • Security Assertion Markup Language (SAML)
  • eHerkenning, which is a SAML implementation that is available only for the Netherlands.

To access the identity broker on the console:

  1. Log in to your OneWelcome Identity Platform and select your tenant, if required.

  2. In the top-right of your browser, in the Applications menu, select Configuration.

    Applications menu

  3. On the left, select Identity broker and then select Identity providers.

    ID Broker on the console

OIDC identity providers

To configure the two-way communication between the OneWelcome Identity Platform and the external IDP, you need to configure settings in both the OneWelcome Identity Platform and the external IDP.

For the OneWelcome Identity Platform, you configure the settings on the console. For each IDP, you need to configure the following information in the identity broker module:

  • Basic information

  • Connection details

  • Federation requests

  • Attribute mappings

Configure OIDC basic information

  1. On the Identity providers page, select Add identity provider, and then select OpenID Connect.

    OIDC basic information

  2. In the Basic information section, add a Display name.

    The display name is used in the OneWelcome Identity Platform, but is not visible to your users.

  3. (Optional) Add any Domain aliases.

    Domain names are used to select an IDP when acr_values are not used to select the IDP and the authentication request to the identity broker contains a login_hint parameter with an email address as a value.

  4. (Optional) Add a Description.

  5. Set the state of the IDP:

    • To make the IDP available to users after you save it, select the Active check box.

    • To allow you to save an incomplete configuration or to prevent the IDP from being available to users after you save it, clear the Active check box.

Configure OIDC connection details

Before you can configure the connection details, you need to get the following information from the external IDP:

  • Client ID: This is the OIDC application (client) ID that identifies the external IDP.

  • Client secret: The OneWelcome Identity Platform sends the OIDC shared secret to authenticate the request with the external IDP.

  • Well-known configuration endpoint: This URL can have different names in different IDPs, such as the OpenID Provider Configuration Document, Discovery Document URL, or simply Endpoint. If this URL doesn't exist in the external IDP, you manually configure the other endpoints in the OneWelcome Identity Platform.

The OIDC protocol requires that all potential redirect URIs are specified in an allowlist. The console lists all the redirect URLs that the identity broker might use. The domain specified in the authentication request determines the actual domain. Ensure that the redirect URI used in the authentication request is included in the allowlist in the external IDP that you are configuring.

  1. In the Connection details section, enter the Client ID.

    OIDC connection details

  2. Select an Authentication method:

    • No Authentication

    • Private key JWT

    • Client secret post

    • Client secret basic

  3. To enhance security with Proof Key for Code Exchange (PKCE), select the PKCE check box.

    If the authentication method is No Authentication, PKCE is required and you cannot clear the check box.

    PKCE mitigates the risk of interception and the misuse of authorization codes. The OneWelcome Identity Platform supports only the SHA-256 transformation method.

  4. If the authentication method is either Client secret post or Client secret basic, enter the Client secret.

    Client secret

  5. Enter the Well-known configuration endpoint and select Load.

    Well-known configuration endpoint and other endpoints

    When you load the well-known configuration endpoint, the Authorization endpoint, Token endpoint, Issuer, User information endpoint, and JWKs URI fields populate automatically.

    If the external IDP doesn't have the well-known configuration endpoint, enter the following information:

    • Authorization endpoint: The user is redirected to this URL to authenticate.

    • Token endpoint: When authentication is successful, an authorization code is sent to this URL to obtain an ID token and an access token.

    • Issuer: The issuer string is used to validate the keys for the ID token signature.

    • (Optional) User information endpoint: This is a protected resource that provides information about a user. In an access token that was issued by your token endpoint, the scopes specify the user attributes that are returned in the response of the user information endpoint.

    • (Optional) JWKs URI: Returns the JWK when you use JWK for signature verification or encryption.

  6. If you do not specify the JWKs URI, you must use certificates:

    Identity provider signing and encryption certificates

    1. Under Identity provider signing certificate, select the certificate. To upload a new certificate, select Create new and upload the certificate.

    2. Under Identity provider encryption certificate select the certificate. To upload a new certificate, select Create new and upload the certificate.

  7. (Optional) To enable support for encrypted JWT, select the Encrypted JWT check box.

    Encrypted JWT options

    1. Select the type of key pairs to use:

      • Use generated key pairs

      • Use custom key pairs: Enter the Encryption key pair and optionally the Next encryption key pair.

        Custom key pairs

    2. Select the JSON web encryption algorithm for the identity provider to use:

      JSON web encryption algorithm

      • RSA_OAEP_256
      • RSA_OAEP
      • ECDH_ES

  8. To ensure that logout requests are propagated to the identity provider to end the user's session, select Single logout, and then enter the End session endpoint URI.

    Single logout check box and end session endpoint URI

Configure OIDC federation requests

Some external IDPs support two workflows:

  • Authentication: For example, authentication might require minimal information, such as a persistent identifier.

  • Identification: For example, you might require additional information for the on-boarding journey, such as the first name, last name, and address.

The federation request allows the identity broker to distinguish between those two purposes. An IDP can have two configurations, based on the purpose. The purpose is provided in the request to the identity broker, towards the external IDP.

Federation requests

  1. Under Federation requests, select the Purposes that the IDP supports. You must select at least one purpose.

    • Authentication: For example, authentication might require minimal information, such as only a persistent user identifier.

    • Identification: For example, identification might require more information than authentication, such as the first name, last name, and address, which you might require for on-boarding.

  2. For each purpose, enter an ACR Value.

    The Authentication Context Class Reference (ACR) claim is the authentication level that is required.

  3. Enter the Scope names for the user attributes that you need.

  4. Enter the Claims for the user attributes that the scopes return.

Map OIDC attributes

Map the user attributes from the IDP to the equivalent user attributes in the OneWelcome Identity Provider.

The IDP sends user attributes as claims in the authentication response. Only mapped attributes are stored and sent to your services.

For example, the IDP might include the first name and last name in one field, whereas your organization splits them into two fields.

Attribute mapping

  1. Under Attribute mappings, select the User identifier that identifies the user in the request.

  2. To map additional claims from the IDP to user attributes in the OneWelcome Identity Platform, select Add attribute mapping.

    Add attribute mapping

  3. Enter the Claim from IDP and select the equivalent OneWelcome attribute.

  4. Repeat to add additional mappings.

  5. Save your IDP configuration:

    • To save an incomplete IDP configuration or a draft that is not available to users, select Save draft.

    • To save the IDP configuration that is available to users, select Submit.

SAML identity providers

To configure the two-way communication between the OneWelcome Identity Platform and the external IDP, you need to configure settings in both the OneWelcome Identity Platform and the external IDP.

For the OneWelcome Identity Platform, you configure the settings on the console. For each IDP, you need to configure the following information in the identity broker module:

  • Basic information

  • Connection details

  • Federation requests

  • Attribute mappings

Configure SAML basic information

  1. On the Identity providers page, select Add identity provider, and then select SAML.

    SAML basic information

  2. In the Basic information section, add a Display name.

    The display name is used in the OneWelcome Identity Platform, but is not visible to your users.

  3. (Optional) Add any Domain aliases.

    Domain names are used to select an IDP when acr_values are not used to select the IDP and the authentication request to the identity broker contains a login_hint parameter with an email address as a value.

  4. (Optional) Add a Description.

  5. Set the state of the IDP:

    • To make the IDP available to users after you save it, select the Active check box.

    • To allow you to save an incomplete configuration or to prevent the IDP from being available to users after you save it, clear the Active check box.

Configure SAML connection details

The SAML connection details include the metadata file that the identity provider will use. You can either provide a URL for the metadata, or provide the metadata XML.

  1. Select the Identity provider metadata:

    • To use a metadata file, select Dynamic from URL.

      SAML connection details

      1. Enter the Metadata URL and click Load.

        The Entity ID (identity provider), Entity ID (service provider), and Preferred binding fields populate automatically.

        If these fields do not populate automatically, validate your metadata URL or manually update the fields.

    • To enter the metadata XML, under Identity provider metadata, select Static XML.

      If certificates expire, you have to manually update them in the configuration.

      Static XML

      1. Enter the Metadata XML.

      2. Enter the Entity ID (identity provider).

      3. Enter the Entity ID (service provider).

      4. Select the Preferred binding type:

        • HTTP Post

        • Artifact

  2. Select or add a Signing key pair that your organization uses for signing messages from the OneWelcome Identity Platform to SAML.

    If you don't select a key pair, the OneWelcome Identity Platform generates one.

    Signing key pair

    1. To add a signing key pair, under Signing key pair, select Add key pair.

      Signing key pair

    2. Enter a Display name for the key pair.

      Add key pair

    3. Select the Private key and the Certificate, and then select Add key pair.

    4. To add another key pair, under Next Signing key pair, select Add key pair.

  3. To encrypt personal data that is sent to the OneWelcome Identity Platform, select the Encrypted assertion check box.

    If you don't add a key pair, the OneWelcome Identity Platform generates one.

    Encryption assertion

    1. Select or add an Encryption key pair.

    2. To add an encryption key pair, select Add Key Pair.

    3. Enter a Display name for the key pair.

    4. Select the Private key and the Certificate, and then select Add key pair.

    5. To add another key pair, under Next encryption key pair click Add Key Pair.

  4. To enable a mutual TLS connection for back-channel communication, select the Enable Mutual TLS check box.

    If you don't add a key pair, the OneWelcome Identity Platform generates it.

    Mutual TLS keystore

    1. Select or add a Mutual TLS keystore key pair.

    2. To add a mutual TLS keystore key pair, select Add key pair.

    3. Enter a Display name for the key pair.

    4. Select the Private key and the Certificate, and then select Add key pair.

    5. Select or add a Mutual TLS truststore certificate.

    6. To add a mutual TLS truststore certificate, select Add certificate.

    7. Enter a Display name, select the Certificate, and select Add certificate.

  5. To ensure that logout requests are propagated to the identity provider to end the user's session, select the Single logout check box.

    SAML single logout

Configure SAML federation requests

Some external IDPs support two workflows:

  • Authentication: For example, authentication might require minimal information, such as a persistent identifier.

  • Identification: For example, you might require additional information for the on-boarding journey, such as the first name, last name, and address.

The federation request allows the identity broker to distinguish between those two purposes. An IDP can have two configurations, based on the purpose. The purpose is provided in the request to the identity broker, towards the external IDP.

Configure the federation requests that the identity provider will handle. You must select at least one type of federation request.

  1. Set the Maximum authentication age.

    The maximum authentication age describes how flexible the response is compared to the authentication instance in minutes. It should be at least three minutes or left empty.

    Federation request

  2. Select the Outbound communication method:

    • GET

    • POST

  3. Select the Purposes that the IDP supports. You must select at least one purpose.

    Purposes

    • If you need only minimal information for logins, select Authentication:

    • If you need additional information for registration, select Identification.

  4. To force users to authenticate at the identity provider, even if they have an existing session, select Force authentication.

  5. To specify which authentication method to use at the external identity provider, enter the Authentication context class reference.

  6. Set the Authentication context comparison value, which is the authentication level that is required:

    • Minimum

    • Exact

    • Maximum

    • Better

Map SAML attributes

The identity provider sends user attributes as claims in the authentication response. Configure the attribute mapping from the IDP to your organization. Only mapped attributes are stored and sent to your services.

Attribute mapping

  1. Click Add attribute mapping.

    Add attribute mapping

  2. Enter the Claim from IDP and the equivalent OneWelcome attribute to map attributes between the identity provider and the OneWelcome Identity Provider.

    Repeat this procedure for each identity provider claim that you want to map to a OneWelcome Identity Provider attribute.

  3. Save your IDP configuration:

    • To save an incomplete IDP configuration or a draft that is not available to users, select Save draft.

    • To save the IDP configuration that is available to users, select Submit.

eHerkenning identity providers

The eHerkenning IDP is a SAML implementation that is relevant only for the Netherlands. It follows the procedure for adding a SAML IDP, except some values are preset.

  1. On the Identity providers page, select Add identity provider and select eHerkenning.

  2. Follow the steps for SAML IDPs.

On this page