This article provides instructions for customer to configure Microsoft Entra ID (previously Azure AD) for Authentication with Matrix42 Pro and IGA solutions. 

Usually, this configuration is carried out by the customer's Entra ID or authentication specialist. It should take no more than half a day to implement and test. Please note that some of the screenshots may appear differently in the customer's Entra ID.

These instructions are applicable to all Matrix42 Pro and IGA solutions (e.g., ITSM, IGA, HR) that use the Secure Access component for authentication.

How to Configure Entra ID with SAML

Enterprise applications

Customer needs to configure their Entra ID to allow Security Access component to fetch user accounts and groups. All following configuration steps are made in the Microsoft Entra admin center.

1. Go to https://entra.microsoft.com  and after login Select Identity → Applications → Enterprise applications.
   
   

   This is NOT an "App Registration", which is created via another path, but might be confused with this.

    
2. Create a new Enterprise Application by selecting “+ New application” from the top menu.
   
3. Select "Create you own application".
   
4. Fill in the name under the “What's the name of your app” and then select the "Integrate any other application you don't find in the gallery (Non-gallery)" option at the end. Now press the “Create” button.
   
5. Now Enterprise application is created. Next step is to assign users and groups for the application. From the overview you can see the next steps. Choose 1. Assign users and groups. 
   This is optional step, and needs to be done only if you want to restrict which users and groups are allowed in this authentication and included to claims.
   
6. Add needed groups that are using SSO in Matrix42 Pro and IGA solutions by selecting + Add user/group.
   
7. Click “Users and Groups”. Then select all the groups that your organization is using for SSO in Matrix42 Pro and IGA solutions and then click "Select".
   
8. Next step is to set up SSO. From overview you can see the next steps. Choose 2. Set up Single sing on. An SSO implementation based on federation protocols improves security, reliability, and end user experiences and is easier to implement.
   
9. Select SAML option.
   
10. Set Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL): 
    1. Identifier (Entity ID) needs to match Secure Access Identity provider Service provider entity ID. (Same as Reply URL but not ending /broker/<tenant>/endpoint -part).
       1. Example Entity ID: https://your-keycloak.example.com/auth/realms/myrealm
          1. In Secure Access (old name ESA), Entity ID can be found from Service provider entity ID and Reply URL can be found from Redirect URI.
    2. Reply URL needs to match Secure Access Identity provider Redirect URI.
    3. Fill in the with your Matrix42 Pro and IGA solutions environment URL.
       1. If you have multiple environments, e.g. test or dev in addition to your production environment, you can add the URI for those later.
11. For example. https://example.m42cloud.com/auth/realms/example/broker/baseline/endpoint

12. Save
13. Copy App Federation Metadata Url and provide that to the Matrix42 consultant who is doing the SSO implementation.
    

API Permissions

API permissions are granted as a minimum set of permission, which means that only the necessary access needs to be allowed to Secure Access application. These permission needs to be configured so that Secure Access can authenticate, connect to Entra ID and read user account and group information. 

1. API permissions can be opened, after application has been registered.
2.  Select “API permissions” from the side bar and on that page select “Add a permission”. If you already have Microsoft Graph > User.Read added, you can leave this as is.
   
3. Select "Microsoft Graph".
   
4. Select API permissions.
   
5. Scroll down to Directory and select “Directory.Read.All” and click “Add permissions”.
   
6. Lastly click “Grant admin consent for <Organization name>” and click “Yes”. After this the application is ready to be used by Matrix42.
   

Permission are used in different functions as listed below:

Adding email and upn claims

But it is highly recommended to also send user's email address from Entra to Secure Access. From there, user email information is sent to Matrix42 Pro and IGA solution. This is needed for the Chat-functionality (if email is missing then the chat is not available). 

To do this, you need to add email-claim:

1. Go to Token configuration, click Add optional claim to add email and upn claims.
2. Select token type: SAML and Claim: email and upn

Adding groups claim

It is also possible to send Groups as claims from Entra ID, to ESA, just with one additional claim configured in Entra console.

Groups claim is needed if permissions are designed to be taken with this SAML authentication to system. If permissions are handled in ESM, and not needed with user authentication, then groups claims are not needed.

Go to Token configuration of your application just created / +Add groups claim

1. Check the Directory roles -checkbox
2. Check that under SAML Group ID is selected
3. Save

More information and next steps for group claim usage:

• Configure: EPE or ESA to use ESM roles
• https://learn.microsoft.com/en-us/entra/identity/hybrid/connect/how-to-connect-fed-group-claims

Optional: Configure Entra ID to emit federated/guest UPN in SAML

This configuration is suggested to be done, if you allow guest users login.

Open your SAML App Registration application

Go to Token configuration

Add optional claim
Select token type = SAML and Claim upn

Click Add to add that token

On this popup checkbox select “Turn on the Microsoft Graph profile permission”, and then click Add

Edit that claim, by selecting Edit option behind three dots

Set Externally authenticated to Yes and Save

Check that your SAML enterprise application Signle sign-on configurations Attributes & Claims utilizes this upn as user.userprincipalname.

Configuration for federated/guest users is now done. 

Their upn will be shown in SAML token in this format: <upn>_<homedomain>#EXT#@<resourcedomain> for example:  john_contoso.com#EXT#@contoso.onmicrosoft.com

This setting doesn't affect Internal users upn format, it is still in normal upn format, for example: john.doe@contoso.com