In this article is described instructions for configuring Matrix42 Secure Access component to be able to authenticate Customers end-users to Matrix42 solutions (like for example IGA, ITSM etc.), build on top of Matrix42 Service Management Platform by using Okta. This process involves authenticating users via cookies and SAML.

Step-by-Step Instructions

1. Login with Secure Access (ESA) Admin (main.admin) to URL domain.com/auth/admin
2. 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.

   

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 Secure Access (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 Secure Access (ESA) login page

Secure Access (ESA) Mappers Configuration

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

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

Screen above is showing, because Secure Access (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 Secure Access (ESA) User.

1. Login with Secure Access (ESA) Admin (main.admin) to URL domain.com/auth/admin
2. 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.

   

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

     

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.

SAML Identity Provider Example

How to Debug Secure Access (ESA) SAML Messages

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 Secure Access (ESA) log to DEBUG level
   1. Inside Secure Access (ESA) container, edit this file:
      /etc/containerpilot/jobs/esa/start_primary
      
      change from:
      --log-level=INFO
      
      to:
      --log-level=DEBUG
   2. Kill java process:
      $ pkill java
   3. To revert changes, change back --log-level to INFO, then kill java process ($ pkill java). Note: if the Secure Access (ESA) container is restarted, all changes will be reverted — the debug level will return to INFO.

Login Video

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