This article provides instructions for customer to configure Microsoft Entra ID (previously Azure AD) for Authentication using OpenID Connect (OIDC) 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.

All the steps below are required, unless separately specified optional.

How to Configure Entra ID for OpenID Connect (OIDC)

Application Registration

Customer needs to configure their Entra tenant to allow Matrix42 Security Access component to fetch user accounts and groups information. Configuration is made after log-in to Entra ID (previously Azure AD) console. 

1. Go to https://entra.microsoft.com and after login Select App registrations (NOTE! This is not an "Enterprise Application", which is created via another path, but might be confused with this).
   
2. Select New registration.
   
3. Enter a name for application.
4. Select correct Supported Account Types depending on your use case. This is very important selection, so if you are not sure what to select, consult someone more experienced with this configuration.
   1. Option 1 - preferred for most cases: If you are building a basic configuration, where all users you want to login to Matrix42 system belong to your tenant, select Accounts in this organizational directory only (<this tenant> only - Single tenant)
   2. Option 2: - In this use case, you are sure that you want users from the other tenant(s) also be able to login to your Matrix42 solutions (you have for example Multi service provider (MSP). 
      Select: Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant). 
      1. Note that when having multi tenant app, Azure will not send groups as names, it sends groups always only as IDs. 
      2. Note! If you select this multitenant option, Matrix42 need to configure all allowed tenants to Identity providers Issuer field as a comma separated list.
         
5. Under Redirect URI, select Web as the platform, and then enter the reply URL of Secure Access (this can be added later if Matrix42 has not yet provided URI).
   
6. Select Register.

How to Set Redirect URI After Creating Application

1. Go to https://entra.microsoft.com and after login, select App registrations.
2. Find and open application you created.
3. Select Authentication from the left menu.
   
4. Add Redirect URI
   Platform type: Web
   Redirect URI: the URL you got from Matrix42 OpenID Connect v1.0 Identity providers Redirect URI -attribute.
   

Certificates & Secrets

Secure Access supports secure connection with Entra ID by using Client Secrets.

Client Secret Instructions

1. In the Microsoft Entra admin center, in App registrations, select your application.
   
2. Select Certificates & secrets > Client secrets > New client secret.
   
3. Add a description for your client secret.
4. Select an expiration for the secret or specify a custom lifetime.
   1. Client secret expiration is limited to 730 days / 24 months (two years) or less. You can't specify a custom expiration longer than 730 days / 24 months.
   2. Microsoft recommends that you set an expiration date which is less than 365 days / 12 months away.
5. Select Add.
   
6. Record the secret's value for use in your client application code.
   

   This secret value is never displayed again after you leave this page. If the secret value is lost / not recorded, then the only way to get a new secret value is to reconfigure one.

    
   

Token Configuration

For basic OpenID Connect (OIDC) login to work, you don't need to add any Optional claim.

Adding Email Claim

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 claim.
2. Select token type: ID and Claim: email
   

Add Groups Token

Optionally, if you want to also send user's group information from Entra to Secure Access, you need to add a groups-claim. 

In Secure Access you can use groups-claim information to calculate userLevel and esm roles:

1. Go to Token configuration, click Add groups claim.
2. Select correct group types, depending on what type of groups you want to send to Secure Access component. 
   1. Usually Security groups is enough, but it depends how customers Entra ID groups have been designed.
3. Choose Customize token properties by type.
   1. Note that the default is Group ID, but with Matrix42 Professional and IGA solution, sAMAccountName is usually a better option if groups are not created directly from Entra.
      
   2. If you want to send cloud groups in the claim as groupIDs, you just select "group type" and select IDs.
      

API Permissions

API permissions are granted as a minimum set of permission. This means that only necessary access needs to be allowed to Secure Access application.

1. Select “API permissions” from the side bar.
2. On that page select “Add a permission”. 
   1. You should already have Microsoft Graph > User.Read added, you can leave this as is.
      
3. Select "Microsoft Graph".
4. Select Delegated permissions
   
5. Scroll down to Directory and select needed permissions.
   1. Permission: User.Read, Type: Delegated
   2. Permission: email, Type: Delegated
      1. This is only required if an email-claim has been configured and is required.
6. Click “Add permissions”.
7. Now the Configured permissions are displayed.
   

Optional: Configure Entra ID to Emit Federated/Guest UPN in OIDC ID Tokens

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

1. Open your App Registration.
2. Select your app that you have created (Riku M42 native connectors in the screenshot). 
3. Go to Token configuration
4. Select Add optional claim.
5. Select Token type as ID and Claim as upn
6. Click Add to add that token.
   
7. A pop up will appear, check the checkbox, and click Add.
   
8. Edit the claim we just configured, by selecting Edit option behind three dots:
   
9. Set Externally authenticated to Yes and Save.

Configuration for federated/guest users is now done. 

Their upn will be shown in ID 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