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
- Log in to the Unifyia platform as an administrator.
- Navigate to Integrations > Data Sources> Identity Provider.
The Identity Provider page appears.
- Select + Add Identity Provider and from the drop-down menu,
select OpenID Connect v1.0.
- 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:
https://<tenantname>.<domainname>.net:<port>/realms/<tenantname>/broker/<alias>/endpoint
- First, add an Alias to uniquely identify the platform tenant, for example,
entra_idp_oidc
- You will notice that the Redirect URL has changed. The given alias name is now added just before
/endpoint.
- 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.
- Login as an admin to the Entra ID portal.
- In the Entra ID admin center, navigate to Identity >
Applications > App
registrations.
- Select New registration.
- Give the application a user-facing display name.
- For Supported account types, select Accounts in this organizational
directory only (unifyia only - Single tenant).
- Under the Redirect URI (optional) section, provide the below information:
- Select the platform type as Web from the dropdown.
- Next, provide a Redirect URI of the Unifyia platform that you have
copied to the text editor.
- Select Register. The sub menu for the registered Unifyia web application
appears.
- Complete the below steps to create the client secret.
- Navigate to Manage > Certificates & secrets on
the sub menu.
- Under Client Secrets, select + New client secret.
- Enter the following details:
- Description: Enter a brief description of the client's secret.
- Expires: Select the expiration period for the client secret.
- Select Add.
- After the client secret string is created, copy its Value and
ID, and copy them to a text editor for later use.
- Navigate to Overview on the sub menu, copy the Directory (tenant) ID to
the text editor.
- From the top menu options, select Endpoints. All the endpoints are displayed.
- Copy the OpenID Connect metadata document (URL) to a text editor.
- 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.
- Log in to the Unifyia platform as an administrator.
- Navigate to Integrations > Data Sources> Identity Provider. The
Identity Provider page appears.
- 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:
- General Information: Provide application details and logo to display
the application icon to the user.
- IdP Configuration (OIDC v1.0): Configuring integrationparameters
- Under General Information, enter the following:
- App Name (required): Provide a name for the IdP, for example, Entra ID.
- Description: Enter a brief description of the identity provider.
- Add a logo for the app: Either drag and drop a file or simply click the
box to upload a logo for the IdP.
- Select Next. You will be directed to the next tab, IdP
Configuration (OIDC v1.0), where you'll configure the necessary OIDC
parameters.
- Under the IdP Configuration (OIDC v1.0) tab, set the below parameters:
- Alias: Provide the same alias name (for example, entra_idp_oidc) that
you have added to build the Redirect URI.
- Domain Name: Provide the domain name of the organization.
- Under OpenID Connect Settings, configure the following:
- Use Discovery Endpoint:
- 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
- Authorization URL, Token URL, Logout URL, User Info
URL, and Issuer values are
auto-populated.
- Validate Signatures option acquires the values
from the metadata URL and the JWKS URL value is
auto-populated.
- If you disable the Use Discovery Endpoint
option, you need to provide the
below
values referring to the OpenID Connect Metadata
Document:
- Authorization URL: Provide the
authorization_endpoint value from the metadata.
- Token URL: Provide the
token_endpoint
value from the metadata.
- Logout URL: Provide the
end_session_endpoint value from the
metadata. This is
optional.
- User Info URL: Provide the
userinfo_endpoint value from the metadata. This
endpoint
points to user profile information.
- 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.
- Validate Signatures: Enable this option by
moving the
slider to the right.
- Enable Use JWKS URL by moving the
slider to the
right.
- JWKS URL: Provide the
jkws_uri
value from the metadata.
- In the last section, provide client data.
- 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.
- 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.
- Client Secret: Provide the client secret from
the above-mentioned text editor.
- Client assertion signature algorithm: Select
HS256. Currently, the platform supports the
HS256 signature algorithm to create a JWT
assertion.
- First Login Flow Override: Select the option PIV/CAC
Authentication broker login.
- Pass Login Hint: Disable this option.
- 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:
- For the newly created IdP select the Edit
- Go to the Mappers
- Select + Add Mappers.The Add Identity Mappers page appears.
- Name: Enter the name of the mapper you are configuring, for example,
role_user.
- Mapper Type: From the drop-down list, select Hardcoded
Role and select the roles as User.
- Select Add.
- If you need to add another hardcoded role, for example, Sponsor, then select + Add
Mappers.
- Name: Enter the name of the mapper you are configuring, for example,
role_sponsor.
- Mapper Type: From the drop-down list, select Hardcoded
Role and select the roles as Sponsor.
- Select Add.
- 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:
- Name: Enter the name of the mapper you are configuring, for example, Entra
Enterprise
Group.
- Mapper Type: Select Hardcoded Group.
- Sync Mode Override: Select Import.
- Group: Select the group to which the groups coming from Entra ID must be
assigned.
- Select Add.
- 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.
- Name: Enter the name of the mapper you are configuring, for example, Entra ID
Engineering Group
- Mapper Type: Select Advanced Claim to Group.
- Sync Mode Override: Select Import.
- Claims: Provide the name of the key and the value. You need to get the Object
IDs of the group from Entra ID.
- Key: Type group. This means that the
group attribute of the user needs to be fetched.
- Value: Provide the Object ID of the first group. Ensure that you
provide this value in parentheses, for example, (133f4516-1d81-46a6-97fb-c5573941fe96).
- 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.
- 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.
- Name: Enter the name of the mapper you are configuring, for example, Entra ID
Engineering Group
- Mapper Type: Select Advanced Claim to Group.
- Sync Mode Override: Select Import.
- Claims: Provide the name of the key and the value. You need to get the Object
IDs of the group from Entra ID.
- Key: Type group. This means that the
group attribute of the user needs to be fetched.
- Value: Provide the object ID of the first group. Ensure that you
provide this value in parentheses, for example, (133f4516-1d81-46a6-97fb-c5573941fe96).
- 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.
- 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.
- 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.
- 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.
- 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.
- 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:
- Launch the Unifyia platform.
- Select Sign In.
- You will notice a button with the user-facing name/logo of the IdP (Entra ID) on the
platform's sign-in page.
- Select it. The Sign-in page of the IdP (Entra ID) appears.
- Enter your credentials.
- You will be logged into the Unifyia platform.