1. Login with ESA Admin (main.admin) to URL domain.com/auth/admin 
    
2. Select correct realm from the left top corner
   
    
3. Open Identity Provider settings from the left side panel
    
   
    
4.  Add new provider by selecting SAML v2.0
   
   
    
5. Import config file (Ask Identity Provider Metadata from the customer)
   
   
    
6. Scroll down and choose Add button (it saves the identity provider)
   
   
    
7. After save copy from the ESA configuration screen an URL listed as Redirect URI and provide this to customer (needed in Okta).
   
    
8. After above configuration is done, a new option to login appears on the ESA login page
    

After using new button to login to Okta, 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 (Okta) - 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 Okta, 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. 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

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.

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

Here is an example video of how to log in. Note that Okta can also be automated (SSO), in which case the ESA login screen is not displayed and the user is redirected directly to Okta. After successful authentication, the user is moved to the Efecte solution for example to portal.