Configure: ESA Entra ID SSO using OpenID Connect (OIDC)
Learn how to set up single sign-on (SSO) using (ESA) with Entra ID.
Configure: ESA Entra ID SSO using OpenID Connect (OIDC)
Learn how to set up single sign-on (SSO) using (ESA) with Entra ID.
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.
Customer instructions: https://docs.efecte.com/customer-instructions/efecte-secure-access-customer-instructions-for-entra-id-configuration-openid
Step-by-Step Instructions
- 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.
- Login to ESA Admin console (with user: main.admin) by going to url
https://<YOUR_ENVIRONMENT_FQDN>/auth/admin
or withpartner.adminuser to urlhttps://<YOUR_ENVIRONMENT_FQDN>/auth/admin/<YOUR_ENVIRONMENT_REALM>/console/. - Select correct realm, by first selecting from top left Manage realms and then clicking link of realm name. Realm selection UI changed in release 2026.1.2 compared to older ones.

-
Open
Identity Providersettings from the left side panel:
- Add
Identity Provider.- Open
Identity Providersfrom left menu, clickAdd provider, selectOpenID Connect V1.0 - Set
Use discovery endpointtoOn. - 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 tenantsDirectory (tenant) ID. - Set Client authentication to
Client secret sent as post.- 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.
- 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.
- Set customers Entra
Application (client) IDtoClient ID attribute. - 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
issuerattribute of this Identity provider, otherwise there is security risk that someone from unwanted tenant can login to portal.You can add multiple tenants to
issuerattribute, separated by comma, do not use spaces.Example of
issuervalue 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/ - Your
OpenID Connect V1.0Identity provider should look like this, before you click “Add”:
- After Adding that Identity Provider, you still need to set these settings:
Prompt: Login-
Accept prompt=none forward from client: On
Validate Signatures: OnUse JWKS URL: On-
JWKS URL: https://login.microsoftonline.com/common/discovery/keys
Trust email: OnFirst login flow override: first broker loginPost login flow: None-
Do not store users: On- 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 thisOffon testing and debugging phase, it helps to debug issues.
- It is recommended to set “
- Open
- Save your
Identity provider. - Create needed mappers to your
Identity provider.- Open identity provider you just created, and go to
Mappers-tab:
-
Username- This is the most important mapper, as this is used in login process to Matrix42 Pro and IGA.
- 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.
-
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).
-
- Open identity provider you just created, and go to
-
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).
- 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”.
- 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”.
- 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 theemail_mapper):
- Open
Clientssettings from the left toolbar:- Select the line related to
Shibbolethauth (for example:https://customer.efectecloud-test.com/shibboleth) having typeSAML. - Open
Client scopes-tab from the toolbar. - Open link ending with
/shibboleth-dedicated. - Check that these mappers are found (if you have more mappers, check section “
userLevel mapper information”):
-
userLevelmapper information - If the followinguserLevelmapper is listed:com:efecte:esm:userLevel:
- Open it by clicking it.
- Depending on your architecture design, you may or may not want to calculate
userLevelinSecure Access. - If you don't want
Secure Accessto calculateuserLevelfor you, you can either remove thisuserLevelmapper, or change it'sSAML Attribute Namein a way that it's not recognized by platform anymore, for example by adding text_Disabledto end of it. - If you want
Secure Accessto calculateuserLevel, thenSAML Attribute Namemust becom:efecte:esm:userLevel
- Select the line related to
- All basic configuration should be now done, so test authentication to Matrix42 Pro or IGA Portal and to Agent UI.
- Remember to also test logging out. And login again after logout, to confirm that logout was successful.
If you are taking userLevel calculation into use in ESA and have that userLevel mapper active, remember to change javascript mapper file on ESA docker. Otherwise you most likely get NoAccess userLevel, when you try to login. Only Matrix42 has access to those javascript mapper files.
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:
- Select correct realm from top left dropdown menu.
- Open
Authenticationfrom the left side panel. - On browser (Build-in) select 3 dots button from left, and select
Duplicate.
- Give it a name and a description and then click
Duplicate.- 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.
- 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.
- Set
Identity Provider RedirectortoAlternativefrom the drop-down menu:
- NOTE! If
Identity Provider Redirectoris missing from the browser steps, you can add it from here:
- NOTE! If
- Configure the default identity provider by pressing the edit button (cogwheel).
-
Alias= Name of the configuration. -
Default Identity Provider= Alias of the existingIdentity Provider. Check the alias from yourIdentity Provider.
- Configure that
AliastoDefault Identity Providerattribute, by selecting cogwheel:
- And now typing the new
Aliasname to it. Now set theAliasof theIdentity Providerto be theDefault Identity Providerattribute ("oidctest"in the screenshot):
- Configure that
-
- Change the Identity Provider's
Promptsettings from Advanced section, if needed:
- Unspecified - This option leaves decision job to Entra ID.
- None - This option is always doing Entra ID login, no possibility to use Entra ID credentials manually.
- 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.
- 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.
-
Select_Account - User can choose the account from sessions inside of browser (no login needed).
- Check Secure Access flows:
Authentication -> Flows.- If
Browser flowuses eitherEfecte LoginorBuilt-in Browser, change your new flow toBrowser flowin the next step.

- Find your new flow (in this case named to M42 browser SSO) and click its three dots and select
Bind flow:
- Select
"Browser flow"and clickSave.
- If
- ESM logout URL's and Portal Logout
- 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).
- Logout URL can be, for example, customers intranet address, or whatever page customer wants to use.
- ESM logout URL setting is under Maintenance / System Settings / Edit platform settings.
- ESM logout URL setting is under
Maintenance - System Settings - Edit platform settings - sessionterminator.redirecturl- Setting format is (give your logout page address after
?return=):<your matrix42 system url>/Shibboleth.sso/Logout?return=https://companyintranet.companyexample.com - The full setting value would look like this:
- Setting format is (give your logout page address after
- For the Portal (ssc), the Logout URL setting is on ssc admin:
<your matrix42 system url>/ssc/admin, underSetting - General Setting - Sign-out page:
- We recommended using the following format on the Portal settings:
/Shibboleth.sso/Logout?return=https://mycompanyintra.company.com - Note that Portal Sign-out page is per tenant, so every tenant can have own logout page if needed.
- We recommended using the following format on the Portal settings:
- 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).
- Test autologin and also test the logout.
Emit Federated/Guest UPN
If Entra side was configured to Emit Federated/Guest UPN in OIDC ID Tokens, then you need to delete username-prohibited-characters validator from username, as that prevents having # and other special characters in username.
- Select correct realm
- Go to Realm settings / User profile -tab
- Select username
- In
Validationssection, Deleteusername-prohibited-charactersvalidator
- Save
Table of Contents