Integrate Entra ID as an IdP Using SAML Protocol

This tutorial provides instructions for configuring Microsoft's Entra ID as an identity provider for identity federation using the SAML protocol.

Prerequisites

  • You need to have admin credentials to access the 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.
  • The Unifyia platform needs to be configured as an Enterprise application on the Entra ID portal.
  • 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.
  • You require a Reply URL and Service Provider Entity ID.

How to get a Reply URL (Assertion Consumer Service URL) and the Service Provider Entity ID 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.
  4. Navigate to the IdP Configuration (SAML v2.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
  5. First, add an Alias to uniquely identify the platform tenant. g: entra_idp_saml
  6. You will notice that the Redirect URL has changed. The given alias name is now added just before /endpoint.
  7. This is the Reply URL of the platform. Copy it to a text editor.
  8. Next, scroll down to find the Service Provider Entity ID. Copy it to the text editor.
  9. You will need these two values 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 Enterprise application with the Identity Provider (Entra ID).

  1. Login to the Entra ID application as an administrator.
  2. In the Entra ID admin center, navigate to Entra ID > Enterprise Applications > All applications.
  3. Select New application.
  4. The Browse Microsoft Entra Gallery pane opens.
  5. Select Create your own application.
  6. Provide a name for the application, for example, Unifyia_Platform_SAML and select the option Integrate any other application you don't find in the gallery (Non-gallery). Select Create.
  7. The Overview page is displayed. On the 2. Set up single sign on block, select Get started.
  8. On the Single sign-on page, select the method as SAML.
  9. Select the Pencil icon on the top right corner of the Basic SAML Configuration section to edit the values. Enter the following values:
    1. Identifier (Entity ID): Select Add Identifier and provide the Service Provider Entity ID value that you copied from the Unifyia platform to a text editor. The Entity ID uniquely identifies the Unifyia application within Microsoft Entra ID and must be distinct from all other applications in the Microsoft Entra tenant.
    2. Reply URL (Assertion Consumer Service URL): Select Add reply URL and enter the Reply URL that you have built and copied to the text editor. The reply URL is the endpoint where the application expects to receive the authentication token, also known as the Assertion Consumer Service (ACS) in SAML.
    3. Sign On URL (Optional): Provide the same URL that you have entered for the Reply URL.
    4. Logout URL (Optional): Provide the same URL that you have entered for the Reply URL.
  10. Select Save.
  11. Next, select the Pencil icon on the top right corner of the Attributes and Claims You need to add four claims. Select Add new claim and enter the values as seen in the table below one after the other. Select Save after each claim is added.
    12. Name Source Attribute
    firstName Select the value user.givenname from the dropdown.
    lastName Select the value user.surname from the dropdown.
    email Select the value user.primaryauthoritativeemail from the dropdown.
    username Select the value user.primaryauthoritativeemail from the dropdown.
  12. Once the attributes are added, select the Cross icon to return to the overview page.
  13. Navigate to Manage > Users and groups. Select Add user/group.
  14. On the Add Assignment pane, select None Selected.
  15. Search for and select the user or group that you want to assign to the application.
  16. Select Select.
  17. Select the Cross icon to close the page. You will notice that the selected users or groups are listed.
  18. Navigate to Manage > Single sign-on.
  19. Under the SAML Certificates section, copy the App federation metadata URL by selecting the copy icon to a text editor. This URL is the value required for the SAML Entity Descriptor field on the Unifyia platform. This URL auto-populates the required values while configuring Entra ID as an SAML IdP on the Unifyia platform.
  20. Paste the App federation metadata URL in a browser to view the IdP (Entra ID) metadata. Save this XML file, as you will need specific values from it if you choose to manually configure Entra ID as an SAML IdP on the Unifyia platform. Note that the Use Entity Descriptor toggle is available only during the initial IdP configuration on the Unifyia platform. Once the configuration is saved, the toggle will no longer be visible.

Step 2: Add Entra ID as a SAML IdP on the Unifyia Platform

Prerequisites

  • You need the App federation metadata URL from Entra ID which is the value for SAML Entity Descriptor.
  • Ensure to provide the same alias name (for example, entra_idp_saml) that you have added to build the Reply URL.
  • You will need to extract the following metadata values and URLs from the App federation metadata XML file of Entra ID if you choose to enter them manually rather than using the SAML Entity Descriptor to auto-populate the fields. However, the manual entry method is not recommended.
    • Single Sign-On Service URL
    • Identity Provider Entity ID
    • Single Logout Service URL
    • X509 Certificate of the IdP: Search for the X509 Certificate value in the XML file. Copy the certificate within the tags <ds:X509Certificate> </ds:X509Data> provided for the Location parameter. This valued will be used for the Validating X509 Certificates field.

Integration Steps

  1. Log in to the Unifyia platform as an administrator.
  2. Navigate to Configuration > Data Sources> Identity Providers. The Identity Providers page appears.
  3. Select + Add Identity Provider and from the drop-down menu, select SAML v2.0. The page to configure the identity providers opens. Adding IdP involves two steps:
    1. Adding the General Information
    2. Configuring parameters for IdP Configuration (SAML v2.0)
  4. Under the tab 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 and the application you will be using it with.
    3. Add a logo for the app: Either drag and drop a file or simply click to upload a logo for the IdP.
    4. Select Next. You will be directed to the next tab, IdP Configuration (SAML v2.0), where you'll configure the necessary SAML parameters.
  5. Under the IdP Configuration (SAML v2.0) section, set the below parameters:
    1. Alias: Provide the same alias name (for example, entra_idp_saml) that you have added to build the Redirect URI.
    2. Domain Name: Provide the domain name of your organization, for example, utopia.com.
    3. Endpoints: Select the link SAML 2.0 SERVICE PROVIDER METADATA to get the server metadata to configure in the IdP server. This metadata file is generated correctly only after you save the configuration.
    4. Under SAML Settings, configure the following:
      1. Use Entity Descriptor: Enable this option as you will use the App federation metadata URL to acquire the required data from the metadata file. If you disable this option, you need to provide the required values manually by referring to the App federation metadata XML file form the Entra ID portal. It is recommended to always enable this option and provide the metadata URL to avoid mistakes in copying the URLs. As mentioned earlier, the Use Entity Descriptor toggle is available only during the initial IdP configuration on the Unifyia platform. Once the configuration is saved, the toggle will no longer be visible.
      2. SAML Entity Descriptor: Enter the App federation metadata URL that you copied to a text editor. Once you provide this value, then the
        1. Single Sign-On Service URL, Identity Provider Entity ID, Single Logout Service URL, and Validate Signatures values are auto-populated.
        2. Allow Create flag is enabled. This allows the IdP to create a new user account to represent the principal if the user does not already exist when an authentication request is received.
        3. HTTP-POST Binding for AuthnRequest flag is enabled. This allows the SAML response from the IdP to the Service Provider to be sent using the HTTP-POST method.
        4. HTTP-POST Binding Response flag is enabled. This allows the SAML logout request to be sent using the HTTP-POST method.
        5. Validate Signatures flag is enabled and it acquires the certificate from the metadata URL. Enabling this option ensures that all the signatures are validated.
      3. NameID Policy Format: Select the option Email from the dropdown.
      4. Principal Type: This denotes which part of the SAML assertion is used to identify and track the user identities. Select Subject Name ID from the dropdown.
      5. Force Authentication: Enable this option. The system prompts the user for authentication credentials when the browser is closed and reopened regardless of whether the user still has a valid session.
    5. Client session logout: Enable this option. The SAML logout will also end the session of the client (Unifyia platform).
  6. Select Add.

You have successfully added Entra ID as an IdP via SAML 2.0 protocol. You can view the newly added IdP under the Identity Providers list page. In the edit mode, under the IdP Configuration (SAML v2.0) section, the Endpoints link is visible. Select the link SAML 2.0 SERVICE PROVIDER METADATA to view the server metadata. This metadata file is generated correctly only after you save the configuration.

The next step is to edit the newly created IdP and add mappers.

Add Mappers

Mappers are components that allow you to customize the way user attributes, roles, and group memberships between IdPs and Unifyia. For the newly created IdP select the Edit icon. Go to the Mappers section and follow the succeeding sections to learn more about the three types of mappers – Attribute Importer, Role, and Group that you need to add.

Attribute Importer

You need to add four user attributes mapping between the Entra ID and the Unifyia platform. The user attributes are username, firstname, lastname, and email. Follow the below steps.

  1. Select + Add Mappers.The Add Identity Mappers page appears. Add the first attribute with the values as seen in the table. Select Save after each user attribute is added.
  2. Repeat the above step until all the user attributes are added.
List of the Attribute Mappers to be Added
Name Mapper Type Sync Mode Override Attribute Name User Attribute
First Name Attribute Importer Import firstName firstName
Last Name Attribute Importer Import lastName lastName
Email Attribute Importer Import email email
User Name Attribute Importer Import email username

Harcoded Role Mapper

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, e.g., 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, e.g., 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 Mapper

For users from the integrated IdP, you can assign hardcoded groups. 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.
  • Advance Claim to Group mapper is currently not implemented for Entra ID using SAML protocol.

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, e.g., Entra ID 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.

You have now successfully added the mappers and configured the IdP using the SAML v2.0 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.
  5. The Sign-in page of the IdP (Entra ID) appears.
  6. Enter your credentials.
  7. You will be logged into the Unifyia platform.

Back Next
On this page
Related Links
How-To-Guides