1. Install https root certificate to Secure Access (This can be done only by Matrix42)
Add Entra ID related https certificates to Secure Access component. These certificates are needed to establish secure connection between Entra ID and Secure Access systems.

Follow guidance on chapter “Add Microsoft related certificates to Secure Access”: https://docs.efecte.com/configure-authentication/download-and-install-certificates-to-secure-access-esa
 

2. Login to Secure Access to create SAML v.2.0 Identity Provider
Login to ESA Admin console (with user: main.admin) on url https://<YOUR_ENVIRONMENT_FQDN>/auth/admin 
or with partner.admin user on url https://<YOUR_ENVIRONMENT_FQDN>/auth/admin/<YOUR_ENVIRONMENT_REALM>/console/
 

Select correct realm from the top corner

 

Select Identity providers from the menu

3. Add SAML v2.0 Identity Provider

4. Copy from the ESA configuration screen an URL listed as Redirect URI and provide this to customer (that needs to be configured to their Entra application as redirect uri).



5. Fetch IdP metadata from Entra

Set Use entity descriptor On and set SAML entity descriptor value to url customer gave from their Entra (App Federation Metadata URL)

 

6. Remember to check "Allowed Clock Skew" setting and define that for example 3 or 5 seconds.The default value is '0' (which means that any mismatch between ESA's internal clock and an Identity Provider clock will cause the error: "Assertion expired".




 

7. After above configuration is done, a new option to login appears on the ESA login page

8. Test login and logoff with various users

1. In order to enable SAML-based login for ADFS, Customer has to configure AD with these instructions.
    
2. Authentication task for authentication needs to be configured in Service Management platform, before configuring Secure Access component.
   • How to configure authentication task?
      

Validate that configuration is stored in Secure Access correctly (with same information as set in provisioning task configuration). Login with ESA Admin(main.admin) to URL domain.com/auth/admin

1. Select correct realm from the top corner
   
   
    
2. Select Identity providers from the menu
   
    
3. In the list, should be shown same provisioning task for authentication, which was created to Service Management platform.
   
    
4. Check that configuration is transferred correctly from Service Management platform to Secure Access component. 
   
    
5. Add and enable the following settings, if necessary:
   • Backchannel Logout 
     • Backchannel logout is a mechanism designed to ensure that when a user logs out from an identity provider (IdP/ESA), they are also logged out from all the associated relying parties (RPs) or applications.
     • If "Want AuthnRequests signed" is enabled in ADFS, backchannel logout is mandatory.
   • HTTP-POST Binding Response
   • HTTP-POST Binding for AuthnRequest
   • Validate Signature
     
      
6. If the authentication requests sent to the AD FS instance are expected to be signed, enable the Want AuthnRequests Signed option. Then the SAML Signature Key Name field is displayed.
   
    
7. Set the SAML Signature Key Name field option to CERT_SUBJECT. AD FS expects the signing key name hint to be the subject of the signing certificate.
   
    
8. If the AD FS is set up to respond with name ID in the Windows Domain Qualified Name format, set the NameID Policy Format field accordingly.
   

If, by any chance, after using new button to login to Entra, below screen is visible on the screen, it means, ESA needs further configuration.      
                    

In order to pass the User from ESA to other systems (ESM, ESS, IGA) - ESA must be aware of context of the User. For that purpose, ESA stores a bit of metadata, describing each User which attempted to login.

Screen above is showing, because ESA is unable to retrieve all of the needed data from Identity Provider (Entra) - and is asking the User to manually input all required data.

We can overcome that, and prepare an automation which will automatically map attributes with data coming from the Entra, to attributes required by ESA User.

1. Login with ESA Admin (main.admin) to URL domain.com/auth
   
    
2. Select correct realm from the top corner menu
   
   
3. Open Identity Provider settings from the left side panel
   
    
4. Go to Mappers section. Here is an example of how they should be defined.
   
    

• For email use the mapper type Attribute Importer.
  Map the user attribute email to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  
• For username use the mapper type Username Attribute Importer.
  Map the username attribute username to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  
• For surname use the mapper type Attribute Importer.
  Map the user attribute lastName to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  
• For given name use the mapper type Attribute Importer.

Map the user attribute firstName to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname

 

If group mapper is needed Add Groups mapper into Identity providers settings.
Map the user attribute groups to http://schemas.xmlsoap.org/ws/2008/06/identity/claims/groups

Follow also 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.

After these steps:

• Make sure that a Person datacard is created in ESM.
• Make sure that Person has right value in servlet.auth.person.uid.attribute.code - it will be used later on, as a login name.

When above steps are completed, during login process, ESM will create missing User object, link it with already existing Person - and proceed to startup page of ITSM for given role.

NOTE! If there is no reason to store users in ESA, you can select Do not store users in identity provider. This means that users are not saved to ESA. If user data contains sensitive information this can be used, for example social security number. Note that after this you cannot see the user in ESA anymore, mappers will work as usual. By default users are stored to ESA. 

There are two options:

1. Install SAML message decoder to your browser. The SAML decoders are available as browser extensions (e. g. SAML Tracer for Firefox, SAML Chrome Panel for Google Chrome).
   
   OR
2. Set the ESA log to DEBUG level
   
   
   1. Inside ESA container, edit this file:
      /etc/containerpilot/jobs/esa/start_primary
      
      change from this:
      --log-level=INFO
      
      to this:
      --log-level=DEBUG
      
       
   2. then, kill java process:
      $ pkill java
      
       
   3. to revert changes, change back "--log-level" to INFO,  then kill java process ($ pkill java)
      
      NOTE ! if the ESA container is restarted, all changes will be reverted - in this case, the debug level will be back to INFO)
      
       

ESA log can be found from ESM UI. 

1. Log into Efecte as root level user
2. Select IGA module
3. Select EPE/ESA configuration
4. Select ESA logs and keycloak.log
   

If customer wants to redirect users to SSO provider (no need to see the Secure Access login page first), 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 some name and description and then click Duplicate

Note! If you don't create duplicate, and instead modify built-in browser flow, next ESA Keycloak version upgrade might override your changes.

5. Set Identity Provider Redirector to be 'Alternative'

NOTE! If Identity Provider Redirector is missing from the browser steps, you can be add it from here:

4. Configure the default identity provider from "wheel config button". Alias = Name of the configuration. Default Identity Provider = To automatically redirect to an identity provider set to the alias of the identity provider.

Check alias from your Identity provider which you have done for SAML in previous steps on this guide

Configure that alias to Default Identity Provider attribute, by selecting wheel and giving some new aliasname to it and set your Identity provider alias to Default Identity Provider attribute. Requirement: Alternative.

5. Change the Identity Provider's prompt settings from Advanced section if needed. Consult correct value from customer, depending how they want autologin to work.

• 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)
  

6. Check ESA flows: Authentication -> Flows. If Efecte Login is Used by Browser flow or Built-in Browser is Used by Browser flow, change your new flow to Browser flow in step 6.1 

6.1 Select your new flow (in this case named to M42 browser SSO) and three dots and Bind flow

6.2 Select browser and save the changes

7. Configure portal and ESM logout url's

If you don't configure those correctly, after logout Secure Access will try to autologin user back to Matrix42 Core, Pro and IGA (user can end up in logout-login loop. Logout url can be for example customers intranet address, or what ever page customer wants to use.

ESM logout url setting is under Maintenance / System Settings / Edit platform settings

Setting: sessionterminator.redirecturl    

Setting format is <your matrix42 system url>/Shibboleth.sso/Logout?return=https://companyintranet.companyexample.com

 from screenshot, give your logout page address after ?return=

Portal (ssc) logout url setting is on ssc admin <your matrix42 system url>/ssc/admin  under Setting / General

Setting: Sign-out page

Portal Sign-out page is per tenant, so every tenant can have own logout page if needed.

8. Test autologin and test also logout

Additional autologin related config, if partners or customers need to login to Secure Access Admin with local or directory accounts

If partners or customers need to login with https://YOUR_ENVIRONMENT_FQDN/auth/admin/YOUR_ENVIRONMENT_REALM/console/ url to Secure Access admin on same realm which you enabled for autologin, do following steps.

Prerequisite:

• Create "Browser flow" without autologin, if you don't already have one.

Actual steps:

1. Select correct realm to which you want to allow login with customer.admin or partner.admin
2. Select clients
3. Select security-admin-console client
4. Open advanced tab
5. Set override to "Browser Flow" to flow with no autologin (you created it in prerequisite step)
6. Test login and logout with customer.admin or partner.admin