Integrate Entra ID as an IdP Using OIDC Protocol

This tutorial provides instructions on integrating Microsoft's Entra ID as an indentity provider for identity federation over the OpenID Connect (OIDC) protocol.

Prerequisites

  • You need to have admin credentials to access the Microsoft Entra ID portal.
  • You need to have admin credentials to access the Unifyia Platform.
  • Create a group for Entra ID users and configure a workflow for it on the Unifyia platform.
  • If a group is not created and configured for the IdP on the platform and mapped to the IdP groups, then ensure to define a default workflow. This workflow would be assigned to all the users coming in from the IdP. Refer to the Create Workflow tutorial for more information.
  • Redirect URI of the Unifyia platform.

How to get a Redirect URI of the platform

  1. Log in to the Unifyia platform as an administrator.
  2. Navigate to Integrations > Data Sources> Identity Provider. The Identity Provider page appears.
  3. Select + Add Identity Provider and from the drop-down menu, select OpenID Connect v1.0.
  4. Navigate to the IdP Configuration (OIDC v1.0) You will find the Redirect URL displayed on the page. The format of the URL will be as below:
  5. https://<tenantname>.<domainname>.net:<port>/realms/<tenantname>/broker/<alias>/endpoint
  6. First, add an Alias to uniquely identify the platform tenant, for example, entra_idp_oidc
  7. You will notice that the Redirect URL has changed. The given alias name is now added just before /endpoint.
  8. This is the Redirect URI of the platform. Copy it to a text editor. You will need this URI while adding the Unifyia platform as an application on the Entra ID Portal.

Step 1: Add Unifyia Platform as an application on the Entra ID Portal

The Unifyia platform needs to be registered as an application with the Identity Provider (Microsoft Entra ID).

Prerequisites

  • You need to have admin credentials to access the Microsoft Entra ID portal.
  • Redirect URI of the Unifyia platform

Follow the below steps to register Unifyia as an application on Entra ID.

  1. Login as an admin to the Entra ID portal.
  2. In the Entra ID admin center, navigate to Identity > Applications > App registrations.
  3. Select New registration.
  4. Give the application a user-facing display name.
  5. For Supported account types, select Accounts in this organizational directory only (unifyia only - Single tenant).
  6. Under the Redirect URI (optional) section, provide the below information:
    1. Select the platform type as Web from the dropdown.
    2. Next, provide a Redirect URI of the Unifyia platform that you have copied to the text editor.
  7. Select Register. The sub menu for the registered Unifyia web application appears.
  8. Complete the below steps to create the client secret.
    1. Navigate to Manage > Certificates & secrets on the sub menu.
    2. Under Client Secrets, select + New client secret.
    3. Enter the following details:
      1. Description: Enter a brief description of the client's secret.
      2. Expires: Select the expiration period for the client secret.
    4. Select Add.
  9. After the client secret string is created, copy its Value and ID, and copy them to a text editor for later use.
  10. Navigate to Overview on the sub menu, copy the Directory (tenant) ID to the text editor.
  11. From the top menu options, select Endpoints. All the endpoints are displayed.
  12. Copy the OpenID Connect metadata document (URL) to a text editor.
  13. Use the Application (client) ID, Client secret, Directory (tenant) ID, and OpenID Connect metadata document (URL) to configure the Identity Provider in the Unifyia platform.

Step 2: Integrate Entra ID as an OIDC IdP on the Unifyia Platform

Prerequisites

  • From the previous step, you have,
    • Tenant ID (Directory ID)
    • Client ID (Application ID)
    • Client Secret (Client Credentials)
    • the OpenID Connect metadata document (URL) from the previous step. Copy and paste this URL into a web browser. Entra ID metadata is displayed.
  • Ensure to provide the same alias name, (for eample, entra_idp_oidc) that you have added to build the Redirect URI.
  • You need the following data from the OpenID Connect metadata document (URL).
    • Discovery Endpoint (from the metadata URL).
    • If the Discovery Endpoint is not provided, check for the below data in the metadata URL.
      • Authorization URL
      • Token URL
      • Logout URL
      • User Info URL
      • Issuer
      • JWKS URL

In this section, you will find instructions for configuring Entra ID as an IdP using the OIDC protocol on the Unifyia platform.

  1. Log in to the Unifyia platform as an administrator.
  2. Navigate to Integrations > Data Sources> Identity Provider. The Identity Provider page appears.
  3. Select + Add Identity Provider and from the drop-down menu, select OpenID Connect v1.0. The page to configure the identity providers opens. Adding an IdP involves two steps:
    1. General Information: Provide application details and logo to display the application icon to the user.
    2. IdP Configuration (OIDC v1.0): Configuring integrationparameters
  4. Under General Information, enter the following:
    1. App Name (required): Provide a name for the IdP, for example, Entra ID.
    2. Description: Enter a brief description of the identity provider.
    3. Add a logo for the app: Either drag and drop a file or simply click the box to upload a logo for the IdP.
    4. Select Next. You will be directed to the next tab, IdP Configuration (OIDC v1.0), where you'll configure the necessary OIDC parameters.
  5. Under the IdP Configuration (OIDC v1.0) tab, set the below parameters:
    1. Alias: Provide the same alias name (for example, entra_idp_oidc) that you have added to build the Redirect URI.
    2. Domain Name: Provide the domain name of the organization.
    3. Under OpenID Connect Settings, configure the following:
      1. Use Discovery Endpoint:
        1. Enable this option if you want to use the (OpenID Connect Metadata URL) from Entra ID to acquire and auto-populate the values from the metadata URL. You will find the Discovery Endpoint URL in the OpenID Connect Metadata Document that you have opened in a browser. If you provide Discovery Endpoint value, the
          1. Authorization URL, Token URL, Logout URL, User Info URL, and Issuer values are auto-populated.
          2. Validate Signatures option acquires the values from the metadata URL and the JWKS URL value is auto-populated.
        2. If you disable the Use Discovery Endpoint option, you need to provide the below values referring to the OpenID Connect Metadata Document:
          1. Authorization URL: Provide the authorization_endpoint value from the metadata.
          2. Token URL: Provide the token_endpoint value from the metadata.
          3. Logout URL: Provide the end_session_endpoint value from the metadata. This is optional.
          4. User Info URL: Provide the userinfo_endpoint value from the metadata. This endpoint points to user profile information.
          5. Issuer: Provide the issuer value from the metadata. The server validates issuer claims, in responses from the IdP, against this value. Ensure that you add the Directory (tenant) ID to your Issuer URL post the configuration is complete, for example, https://login.microsoftonline.com/<Directory (tenant) ID>/v2.0.
          6. Validate Signatures: Enable this option by moving the slider to the right.
            1. Enable Use JWKS URL by moving the slider to the right.
            2. JWKS URL: Provide the jkws_uri value from the metadata.
      2. In the last section, provide client data.
        1. Client Authentication: Choose Client secret sent as basic auth. Select this option if the Client Secret is to be sent as a part of the basic authentication for the APIs.
        2. Client ID: You have copied the Client ID value to a text editor after completing the configuration of the Unifyia platform as an application on the Entra ID application. Provide that value here.
        3. Client Secret: Provide the client secret from the above-mentioned text editor.
        4. Client assertion signature algorithm: Select HS256. Currently, the platform supports the HS256 signature algorithm to create a JWT assertion.
        5. First Login Flow Override: Select the option PIV/CAC Authentication broker login.
        6. Pass Login Hint: Disable this option.
  6. Select Add.

You have successfully added Entra ID as an IdP. You can view the newly added IdP under the Identity Providers list page. The next step is to edit the newly created IdP and add mappers. Also, in the edit mode, under the IdP Configuration (OIDC v1.0) tab, you will notice that the Sync Mode is set to Import, and OpenID, Profile, and Email Scopes are set. Do not change these values.

Add Mappers

Mappers are components that allow you to customize the way user attributes, roles, and group memberships are mapped between IdPs and Unifyia.

You need to add two types of mappers - Role and Group.

Role Mappers

This mapper allows an IdP to map all the IdP uses/groups coming into the Unifyia platform to a selected hardcoded role. You can add multiple hardcoded role mappers if you want the users to be given multiple roles. For each role mapper that you add, you need to select a different role. However, this privilege is at the discretion of the organization. Unifyia supports the below roles.

  • Sponsor
  • Registrar
  • Approver
  • Identity Issuer
  • Security Officer
  • Helpdesk Operator
  • Administrator

Follow the below steps to add hardcoded roles:

  1. For the newly created IdP select the Edit
  2. Go to the Mappers
  3. Select + Add Mappers.The Add Identity Mappers page appears.
    1. Name: Enter the name of the mapper you are configuring, for example, role_user.
    2. Mapper Type: From the drop-down list, select Hardcoded Role and select the roles as User.
    3. Select Add.
  4. If you need to add another hardcoded role, for example, Sponsor, then select + Add Mappers.
    1. Name: Enter the name of the mapper you are configuring, for example, role_sponsor.
    2. Mapper Type: From the drop-down list, select Hardcoded Role and select the roles as Sponsor.
    3. Select Add.
  5. As you have configured two roles, each user from the IdP will be assigned two roles while saving to the Unifyia platform database.

Group Mappers

For users from the integrated IdP, you can assign groups in two ways: by using the Hardcoded Group Mapper or the Advanced Claim to Group Mapper. If there is no group mapping, all the IdP users will be assigned to the default workflow present in the Unifyia platform and the policies defined in the workflow will apply to all the IdP users. The default workflow also needs to be defined by the organization before adding the IdP.

NOTE
  • For an organization you can have only one hardcoded group mapper.
  • Also, you can choose either to go with the hardcoded group mapper or Advanced Claim to group mapper but not both for an IdP.
  • If you need to define policies for multiple groups, it is recommended to use the Advanced Claim to Group mapper where you can add multiple group mappings

Hardcoded Group Mapper

This mapper allows an IdP to map all the IdP uses/groups coming into the Unifyia platform to a selected hardcoded group.

Enter the following for the hardcoded group mapper:

  1. Name: Enter the name of the mapper you are configuring, for example, Entra Enterprise Group.
  2. Mapper Type: Select Hardcoded Group.
  3. Sync Mode Override: Select Import.
  4. Group: Select the group to which the groups coming from Entra ID must be assigned.
  5. Select Add.
  6. The mapper is listed under the mapper list.

Advanced Claim to Group Mapper

Prerequisites

  • Object ID of the groups from Entra ID that are being mapped to the Unifyia platform groups.

There are 3 possible combinations of the group mapping using the Advanced Claim to Group mapper.

  • Map specific group of IdP to a specific group on the Unifyia platform
  • Map multiple groups of IdP to a single group on the Unifyia Platform
  • Map multiple groups of IdP to multiple groups on the Unifyia Platform

Map specific group of the IdP to a specific group on the Unifyia platform

Prerequisites

  • Object ID of the group from Entra ID that is being mapped to the Unifyia platform groups.

Enter the following for the Advanced Claim to Group mapper if you want to map a specific group of the IdP to a specific group on the Unifyia platform.

  1. Name: Enter the name of the mapper you are configuring, for example, Entra ID Engineering Group
  2. Mapper Type: Select Advanced Claim to Group.
  3. Sync Mode Override: Select Import.
  4. Claims: Provide the name of the key and the value. You need to get the Object IDs of the group from Entra ID.
    1. Key: Type group. This means that the group attribute of the user needs to be fetched.
    2. Value: Provide the Object ID of the first group. Ensure that you provide this value in parentheses, for example, (133f4516-1d81-46a6-97fb-c5573941fe96).
  5. Regex Claim Values: Enable this option to link the Entra ID groups to Unifyia platform groups. If enabled claim values are interpreted as regular expressions.
  6. Group: Select the group present in the Unifyia platform. All the users of the groups added under the Claims section will be assigned to this selected group, for example, Entra_IdP_Group.

Map multiple groups of the IdP to a specific group on the Unifyia platform

Prerequisites

  • Object IDs of the groups from Entra ID that are being mapped to the Uniyfia platform groups.

Enter the following for the Advanced Claim to Group mapper if you want to map multiple groups of the IdP to a specific group on the Unifyia platform.

  1. Name: Enter the name of the mapper you are configuring, for example, Entra ID Engineering Group
  2. Mapper Type: Select Advanced Claim to Group.
  3. Sync Mode Override: Select Import.
  4. Claims: Provide the name of the key and the value. You need to get the Object IDs of the group from Entra ID.
    1. Key: Type group. This means that the group attribute of the user needs to be fetched.
    2. Value: Provide the object ID of the first group. Ensure that you provide this value in parentheses, for example, (133f4516-1d81-46a6-97fb-c5573941fe96).
  5. Select + Add An Attribute to add multiple group attributes. Ensure to enter the key (group) and its corresponding group Object ID value for the group attribute. If you are adding multiple groups, then the key is the same (group) but the value changes.
  6. Regex Claim Values: Enable this option to link the Entra ID groups to Unifyia platform groups. If enabled claim values are interpreted as regular expressions.
  7. Group: Select the group present in the Unifyia platform. All the users of the groups added under the Claims section will be assigned to this selected group, for example, Entra_IdP_Group.

Map multiple groups of IdP to multiple groups on the Unifyia Platform

You can map multiple groups of an IdP to multiple groups on the Unifyia platform. For this, you need to add multiple Advanced Claim to Group mappers and for each mapper select a different group of the Unifyia platform.

  1. First, add an Advanced Claim to Group Mapper following the steps explained in the section Map specific group of IdP to a specific group on the Unifyia platform.
  2. Next, add another Advanced Claim to Group mapper following the steps explained in the section Map specific group of IdP to a specific group on the Unifyia platform. However, for this mapper, ensure to select a group of the Unifyia platform other than the one selected in the first step.
  3. You can add as many Advanced Claim to Group mappers as you need but each time ensure that you are mapping the IdP to Unifyia groups as required.

You have now successfully added the mappers and configured the Entra ID as an IdP using the OIDC protocol.

Test Configuration

Prerequisites

  • You must have valid credentials to access Entra ID.
  • You must be a user of the Entra ID groups that are mapped to the Unifyia platform groups.

Follow the below steps to log in to the Unifyia platform using Entra ID credentials:

  1. Launch the Unifyia platform.
  2. Select Sign In.
  3. You will notice a button with the user-facing name/logo of the IdP (Entra ID) on the platform's sign-in page.
  4. Select it. The Sign-in page of the IdP (Entra ID) appears.
  5. Enter your credentials.
  6. You will be logged into the Unifyia platform.