How to Configure Authentication for Entra ID SSO using OpenID Connect (OIDC)?

In this article is described instructions for configuring Secure Access component to be able to authenticate Customers end-users to Matrix42 Pro and IGA solutions (like for example IGA, ITSM etc.), using Entra ID (Azure AD) Single-Sign-On with OpenID Connect (OIDC).

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

Step-by-Step Instructions

1. Matrix42 will install the https root certificate to Secure Access.
   

   If Microsoft related root certificates are not installed, discovery endpoint url doesn't work.

   Also whole authentication doesn't work without those root certificates.

    
2. Login to ESA Admin console (with user: main.admin) by going to url https://<YOUR_ENVIRONMENT_FQDN>/auth/admin 
   or with partner.admin user to url https://<YOUR_ENVIRONMENT_FQDN>/auth/admin/<YOUR_ENVIRONMENT_REALM>/console/.
3. Select your environment Realm from top left dropdown (select one named as your environment).
   
4. Open Identity Provider settings from the left side panel:
   
5. Add Identity Provider.
   1. Open Identity Providers from left menu, click Add provider, select OpenID Connect V1.0
   2. Set Use discovery endpoint to On.
   3. Add URL to Discovery endpoint. This URL must be in v1 format: https://login.microsoftonline.com/[TENANT]/.well-known/openid-configuration. Replace [TENANT] with your Entra tenants Directory (tenant) ID.
   4. Set Client authentication to Client secret sent as post. 
      1. For this configuration, you need Client secret from customers Entra ID tenant application, see article Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC) for more information. 
         
   5. Set customers Entra Application (client) ID to Client ID attribute.
   6. Set Entra application secret value to Client Secret attribute.
      

      If Entra application was configured for multidomain (see Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC)), all allowed domains need to be set to issuer attribute of this Identity provider, otherwise there is security risk that someone from unwanted tenant can login to portal. 

      You can add multiple tenants to issuer attribute, separated by comma, do not use spaces.

      Example of issuer value in multitenant configuration:

      https://sts.windows.net/cbd5fb36-aad31-4d23-9b42-2f11dfaa5b33/,https://sts.windows.net/cbd5fb36-aad31-4d23-9b42-2f11dfaa5b52/,https://sts.windows.net/cbd5fb36-aad31-4d23-9b42-2f11dfaa5b44/

       
   7. Your OpenID Connect V1.0 Identity provider should look like this, before you click “Add”:
      
   8. After Adding that Identity Provider, you still need to set these settings:
      1. Prompt: Login
      2. Accept prompt=none forward from client: On
         
      3. Validate Signatures: On
      4. Use JWKS URL: On
      5. JWKS URL: https://login.microsoftonline.com/common/discovery/keys
         
      6. Trust email: On
      7. Firs login flow override: first broker login
      8. Post login flow: None
      9. Do not store users: On
         1. It is recommended to set “Do not store users” On, otherwise there might be issues when users data changes in Entra ID. But you can have this Off on testing and debugging phase, it helps to debug issues.
            
6. Save your Identity provider.
7. Create needed mappers to your Identity provider.
   1. Open identity provider you just created, and go to Mappers -tab:
      
      1. Username - This is the most important mapper, as this is used in login process to Matrix42 Pro and IGA.
         
         
         1. If this mapper is missing: when user tries to login, they see a screen where they are asked to give login information and their username is weird string.
      2. Email - This claim (information) is not coming as default from Entra, so check that customer has configured this custom email claim to Entra according to guidance: Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC).
         
8. Optional groups mapping - This claim (information) is not coming as default from Entra, so check that customer has configured this groups claim to Entra according to guidance: Secure Access - Customer instructions for Entra ID configuration OpenID Connect (OIDC).
   1. Also, follow this guidance to map groups claims to ESM Roles: https://docs.efecte.com/configure-authentication/configure-esa-to-use-esm-roles  chapter: “How to configure ESA to assign ESM roles from Entra ID”.
      
9. If you added all 3 mappers, your mappers list should now look like this (remember that you need to have at least username_mapper, and it is highly recommended to also have the email_mapper):
   
10. Open Clients settings from the left toolbar:
    1. Select the line related to Shibboleth auth (for example: https://customer.efectecloud-test.com/shibboleth) having type SAML.
    2. Open Client scopes-tab from the toolbar.
    3. Open link ending with /shibboleth-dedicated.
    4. Check that these mappers are found (if you have more mappers, check section “userLevel mapper information”):
       
    5. userLevel mapper information - If the following userLevel mapper is listed: com:efecte:esm:userLevel:
       
       1. Open it by clicking it.
       2. Depending on your architecture design, you may or may not want to calculate userLevel in Secure Access.
       3. If you don't want Secure Access to calculate userLevel for you, you can either remove this userLevel mapper, or change it's SAML Attribute Name in a way that it's not recognized by platform anymore, for example by adding text _Disabled to end of it.
       4. If you want Secure Access to calculate userLevel, then SAML Attribute Name must be com:efecte:esm:userLevel
          
11. All basic configuration should be now done, so test authentication to Matrix42 Pro or IGA Portal and to Agent UI. 
    1. Remember to also test logging out. And login again after logout, to confirm that logout was successful.

Enable Auto-login - Optional, if auto-login SSO is not required 

If customer wants to redirect users directly to the SSO provider (the Secure Access login is not displayed at all), then do the following configuration in Secure Access:

1. Select correct realm from top left dropdown menu.
2. Open Authentication from the left side panel.
3. On browser (Build-in) select 3 dots button from left, and select Duplicate.
   
4. Give it a name and a description and then click Duplicate.
   1. Note! If you don't create a duplicate, and instead modify built-in browser flow, next Secure Access Keycloak version upgrade might override your changes.
      
5. Set Identity Provider Redirector to Alternative from the drop-down menu:
   
   1. NOTE! If Identity Provider Redirector is missing from the browser steps, you can add it from here:
      
6. Configure the default identity provider  by pressing the edit button (cogwheel). 
   1. Alias = Name of the configuration. 
   2. Default Identity Provider = Alias of the existing Identity Provider. Check the alias from your Identity Provider.
      
      1. Configure that Alias to Default Identity Provider attribute, by selecting cogwheel:
         
      2.  And now typing the new Alias name to it. Now set the Alias of the Identity Provider to be the Default Identity Provider attribute ("oidctest" in the screenshot):
         
7. Change the Identity Provider's Prompt settings from Advanced section, if needed:
   
   1. Unspecified - This option leaves decision job to Entra ID.
   2. None - This option is always doing Entra ID login, no possibility to use Entra ID credentials manually.
   3. Consent - Usually not used. Requires the user to give consent to the requested permissions. If the user has already consented in the past, no interaction will occur. However, if they haven't consented yet, the system will present a consent screen showing the permissions that the application is requesting.
   4. Login - Default. Forces the user to log in, even if they are already authenticated. It ensures that the user is re-authenticated and a new session is established.
   5. Select_Account - User can choose the account from sessions inside of browser (no login needed).
      
8. Check Secure Access flows: Authentication -> Flows. 
   1. If Browser flow uses either Efecte Login or Built-in Browser, change your new flow to Browser flow in the next step.
      
      
       
   2. Find your new flow (in this case named to M42 browser SSO) and click its three dots and select Bind flow:
      
   3. Select "Browser flow" and click Save.
      
9. ESM logout URL's and Portal Logout
   1. If you don't configure these correctly, after logout Secure Access will try to autologin user back to Matrix42 Pro and IGA (this can force the user into a logout-login loop). 
      1. Logout URL can be, for example, customers intranet address, or whatever page customer wants to use.
      2. ESM logout URL setting is under Maintenance / System Settings / Edit platform settings.
   2. ESM logout URL setting is under Maintenance - System Settings - Edit platform settings - sessionterminator.redirecturl
      1. Setting format is (give your logout page address after ?return=):  
         <your matrix42 system url>/Shibboleth.sso/Logout?return=https://companyintranet.companyexample.com
      2.  The full setting value would look like this:
         
   3. For the Portal (ssc), the Logout URL setting is on ssc admin: <your matrix42 system url>/ssc/admin, under Setting - General Setting - Sign-out page:
      
      1. We recommended using the following format on the Portal settings: 
         /Shibboleth.sso/Logout?return=https://mycompanyintra.company.com
      2. Note that Portal Sign-out page is per tenant, so every tenant can have own logout page if needed.
10. Test autologin and also test the logout.