Customer need to create OpenID Connect Client to their IdP Keycloak, in order for it to work as IdP for Secure Access.

1. Login to IdP Keycloak
2. Select correct Realm
3. Go to Clients
4. Create client
   Select client type OpenID Connect
   Set descriptive Client ID
   Click Next

5. Set Client authentication On
   Click Next
    

6. Set Valid redirect URIs and Valid post logout redirect URIs

Set Valid redirect URIs by copying Redirect URI from Secure Access Identity provider which you create on next chapter. So you need to set this Valid redirect URI together with Matrix42 when they know it from Secure Access side.

Set Valid post logout redirect URIs, to be for example your company home page.

Web origins should be set automatically, if not, set it correctly manually.
 

1. Add customers Keycloak https certificate to Secure Access (ESA) keystore
   Add customers Keycloak https certificate to Secure Access (ESA) keystore, to enable Secure Access connect to customers Keycloak. This can be done only by Matrix42 persons, as access to host is needed for this. See guidance: https://docs.efecte.com/internal-configuration-instructions/iga-faq chapter How to add certificate to ESA.
   

   Note

   If this certificate is not installed before continuing to next steps, Secure Access is not able to fetch information from IdP Keycloak using discovery endpoint url.

    

2. Login with ESA Admin (main.admin) to URL domain.com/auth/admin
3.  Select correct realm from the left top corner
   
    
4. Open Identity Provider settings from the left side panel
   
    
5.  Add new provider by selecting Keycloak OpenID Connect

6. Name identity provider (as you want)

7. Add URLs for authentication. 
   It is recommended to use discovery endpoint of IdP Keycloak to auto populate those url's with correct values. Customer should give this url, it is on format: https://customeridpkeycloak.com/auth/realms/REALMNAMEHERE/.well-known/openid-configuration
   To use discovery endpoint, set Use discovery endpoint to On and set correct url.
   
   
   
   After that those url's are auto populated.
   
   
    
8.  Optional: Validate signatures can be enabled, customer provides the URL for JWKS
   
    

6. Add Client secret and password (customer provides these from IdP Keycloak)
   
    

1. Scroll down and choose Add button (it saves the identity provider)
2. Check these settings from Identity provider you just created
   
    
3. Set Do not Store Users to On

13. After above configuration is done, a new login button appears on the ESA login page, that fordwards you to customers Keycloak login page

14. Test Login and Logout with more than one account

After using new button to login, below screen is visible on the screen, it means, ESA needs further configuration for the mappers.

                    

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 and it 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 IdP Keycloak, to attributes required by ESA User.

1. Login with ESA Admin (main.admin) to URL domain.com/auth
    
2. Open Identity Provider settings from the left side panel
   
    
    
3. Select Identity provider you did for this Keycloak authentication on previous steps
4. Go to Mappers tab. Here is an example of how they should be defined. 
   Use same attribute names and friendly names as they have been configured to Keycloak being IdP.
   Mappings can differ between different environments, so it is also important to discuss what claims IdP Keycloak is sending and how those should be mapped.
   
   Following three example mappings work in case where IdP Keycloak email claim can be set to email, upn and username attributes.

• For email use the mapper type Attribute Importer and Sync mode override Force.
  
   

• For username use the mapper type Username Attribute Importer and Sync mode override Force.
   

• For upn use the mapper type Username Attribute Importer and Sync mode override Force.
   

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.

Validate/set that you have configured logout url correctly to scc and/or esm depending on where users are going with this authentication.

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.

If you see this screen after authenticating against IdP Keycloak

Then issue is most likely that claims mappings doesn't match between Secure Access and IdP Keycloak. Check/fix configurations on both sides.

If you see this screen after authenticating against IdP Keycloak, it means that Secure Access needs further configuration for the mappers. Check also Claim configurations on IdP Keycloak side.