Set up integration with the enterprise identity provider

Set up integration so that Keycloak delegates authentication to an external enterprise identity provider
Read time 6 minutesLast updated 5 days ago

Integration consists of these phases:
  1. Create a confidential OAuth client in the enterprise IdP.
  2. Configure Keycloak with information about this client and the IdP endpoints.
  3. Update the OAuth client settings in the enterprise IdP, based on the Keycloak configuration.

1. Create a confidential OAuth client in the IdP

In Microsoft Entra ID

Complete these steps:
  1. In Microsoft Entra ID, go to the app registration page.
  2. Create an app registration in the target tenant. The app registration is an OAuth client. At this stage, no configuration is required, except for a name. This name is a de-facto display name that you can change. You can leave all the other default values as is.
  3. Create a secret for this client and save it temporarily to a safe place. This secret is required for the configuration of Keycloak. With this secret, the client is confidential. Keycloak uses this secret for authentication.
  4. Make a note of this information:
    • The application ID (client ID) that is assigned to the new application
    • The directory ID (tenant ID)
    Both values are GUID, but aren't sensitive data, unlike the client secret.

In Okta

Complete these steps:
  1. In the Okta admin console, select the target Okta organization.
  2. Go to Applications > Applications.
  3. Select Create App Integration.
  4. Provide these settings during the creation:
    • Sign-in method:
      OIDC - Open ID Connect
      • Application type:
        web application
      • In the General Settings section:
        • App integration name: a descriptive name for the application. This name is a de-facto display name that you can change later.
        • Grant type: select
          Client Credentials
          .
      • In the Assignments section:
        • Controlled access:
          Allow everyone in your organization to access
        • Enable immediate access:
          Enabled
  5. Make a note of this information:
    • The Client ID that is assigned to the new application. This ID is an arbitrary string in this format:
      0oaibyvqhz1CgoBQC5d7
      .
    • The client secret that Okta has generated. The client secret is sensitive data.

2. Configure Keycloak for integration

Complete these steps:
  1. In the Keycloak admin console, switch to the unity solution realm.
  2. Go to Configure > Identity Providers.
  3. Add a new IdP with these settings:
    1. Select the
      OpenID Connect v1.0
      type for the IdP.
    2. Select an alias for the IdP. The alias must be a short lowercase string without white spaces, for example,
      unity
      . You can use the same alias for different customers. These requirements are to avoid potential issues, because URIs contain the alias.
    3. Select a display name for the IdP.
    4. Ensure that the Use discovery endpoint setting is enabled. Provide the following value for this field:
      • For Entra ID:
        https://login.microsoftonline.com/<tenant-id>/.well-known/openid-configuration
        In this URL, replace
        <tenant-id>
        with the directory ID from the previous step. For example, for the Unity Entra ID tenant, the URL has this format:
        https://login.microsoftonline.com/45b9a1d4-a8af-40da-8eca-96bebddf6fc7/.well-known/openid-configuration
      • For Okta:
        https://<org-name>.okta.com/.well-known/openid-configuration
        In this URL, replace
        <org-name>
        with the name of Okta organization of the enterprise IdP. For example, for the Unity Okta organization, the URL has this form:
        https://unity.okta.com/.well-known/openid-configuration
    5. In the Show metadata section, make sure the values are filled in.
    6. Enter this information:
      • The client ID, which is the application ID from the previous step.
      • The client secret. The client secret must stay in the client configuration, but you don't need to save it. You don't need this value after configuration.
    7. To create the configuration, select Add.
  4. Open the newly created IdP.
  5. On the Settings tab, change these settings:
    • Use PKCE: on
    • PKCE method:
      S256
  6. In the Advanced section, set these values:
    • Scopes: add the
      openid email profile
      scope.
    • Sync mode:
      Force
    • Trust email: on
  7. Select Save.
Make a note of the value of the Redirect URI read-only field in the IdP configuration. You need this value for the next procedure.

Mappers

Mappers map the user attributes from the IdP to the Keycloak user attributes. On the Mappers tab, add the mappers for your identity provider. In the Add Identity Provider Mapper window, leave the Sync mode override option to
Inherit
unless specified otherwise.

In Entra ID

Name

Type

Configuration

Purpose

idp-broker-id
Username template importer
  • Template:
    ${CLAIM.oid}
  • Target:
    BROKER_ID
Maps the Keycloak user to the Entra ID user by its object ID
idp-broker-username
Username template importer
  • Template:
    ${CLAIM.preferred_username}
  • Target:
    BROKER_USERNAME
Maps the Keycloak user to the Entra ID user by its principal name
idp-attribute-email
Attribute importer
  • Claim:
    email
  • User attribute name:
    email
Sets the user email in Keycloak based on the IdP user profile
idp-attribute-firstName
Hardcoded attribute
  • User attribute:
    firstName
  • User attribute value: <empty string>
Sets an empty first name for the user in Keycloak
idp-attribute-lastName
Attribute importer
  • Claim:
    name
  • User attribute name:
    lastName
Sets the user's full name in Keycloak based on the IdP user profile
idp-attribute-enterpriseObjectId
Attribute importer
  • Claim:
    oid
  • User attribute name:
    Custom Attribute\enterpriseObjectId
Sets a special custom attribute to the user ID in the IdP
roles-default-organization-users
Hardcoded role
  • Sync mode override: import
  • Role:
    organization.39943160-54da-49ac-b1c7-bf26adc65855
    for the default organization
Assigns the user to the default organization on the first sign-in

In Okta

Name

Type

Configuration

Purpose

idp-broker-username
Username template importer
  • Template:
    ${CLAIM.preferred_username}
  • Target:
    BROKER_USERNAME
Maps the Keycloak user to the Okta user by its username
idp-attribute-email
Attribute importer
  • Claim:
    email
  • User attribute name:
    email
Sets the user's email address in Keycloak based on the IdP user profile
idp-attribute-firstName
Hardcoded attribute
  • User attribute:
    firstName
  • User attribute value: <empty string>
Sets an empty first name for the user in Keycloak
idp-attribute-lastName
Attribute
  • Claim:
    name
  • User attribute name:
    lastName
Sets the user full name in Keycloak based on the IdP user profile
idp-attribute-enterpriseObjectId
Attribute importer
  • Claim:
    sub
  • User attribute name:
    Custom Attribute\enterpriseObjectId
Sets a special custom attribute to the user ID in Okta
roles-default-organization-users
Hardcoded Role
  • Sync mode override: import
  • Role:
    organization.39943160-54da-49ac-b1c7-bf26adc65855
    for the default organization
Assigns the user to the default organization on the first sign-in

3. Update the OAuth client settings in the enterprise IdP

For Entra ID

For Entra ID, complete these steps:
  1. Go to the app registration for the client, and then go to Properties > Authentication.
  2. To add the Keycloak redirect URI to the application properties, add a platform of type
    Web
    .
    This URI must start with this string:
    https://<solution-domain-name>
    .
    If the URI starts with
    http://127.0.0.1
    , then replace this part with
    https
    and the correct domain name of the solution. This situation occurs when you access the Keycloak admin console through Kubernetes port forwarding.
    The full redirect URI has this format:
    https://<solution-domain-name>*/realms/<realm-name>/broker/<alias>/endpoint
    .
  3. In the app registration properties, go to Token configuration.
  4. Add the following optional claims to the ID token:

Claim

Description

Token type

email
For example:
The addressable email address for this user,
if the user has one.
ID
preferred_username
For example:
Provides the preferred username claim,
which makes it easier for applications
to provide username hints
and show human readable display names.
ID
This change might take two to three minutes to take effect.

For Okta

For Okta, complete these steps:
  1. In the Okta admin console, select the application.
  2. Go to General Settings.
  3. Add the Keycloak redirect URI into the application properties as a sign-in redirect URI. This URI must start with this string:
    https://<solution-domain-name>
    .
    If the URI starts with
    http://127.0.0.1
    , then replace this part with
    https
    and the correct domain name of the solution. This situation occurs when you access the Keycloak admin console through Kubernetes port forwarding.
    The full redirect URI have this format:
    https://<solution-domain-name>/realms/<realm-name>/broker/<alias>/endpoint
    .
  4. Optionally, set a sign-out redirect URI there to the address:
    https://<solution-domain-name>/realms/<realm-name>/protocol/openid-connect/logout
The General tab shows the resulting application settings:
  • Client credentials section:
    • The client ID
  • Client secrets section:
    • The client authentication method:
      client secret
    • The client secrets
  • Application section:
    • The application name:
      unity-keycloak
    • The application type:
      Web
    • For the grant type:
      • For the client that acts on its behalf:
        Client credentials
      • For the client that acts on the user's behalf:
        Authorization code
  • User consent section:
    • The user consent set as required
  • Login section:
    • The sign-in redirect URI:
      https://id.dev.transformation.unity.com/realms/sample/broker/okta/endpoint
    • The sign-out redirect URI:
      https://id.dev.transformation.unity.com/realms/sample/protocol/openid-connect/logout
    • The entity that can initiate the login:
      App only
  • Federation Broker Mode section:
    • Immediate app access with this mode: enabled

Next steps

Rotate the client secret of the SSO application