Configure: Secure Access (ESA) for ESM role assignment
Configure either EPE or ESA to assign ESM Roles for users
Configure: Secure Access (ESA) for ESM role assignment
Configure either EPE or ESA to assign ESM Roles for users
This article describes how to configure either Native Connectors (EPE) or Secure Access (ESA) to link application/directory group to ESM Role.
Note!
Please note that Secure Access (ESA) rarely needs group information because usually it is managed by Native Connectors (EPE). EPE usually brings the MemberOf data to ESM and from there to ESS.
All group names and IDs must originate from the Identity Provider (IdP).
User access levels (userLevel) are determined based on IdP-provided group memberships.
ESM Roles are assigned via external identifiers, mapping IdP groups to roles in the solution.
ESM Role assignment becomes fully automated based on the user’s IdP groups.
Note!
Do not ever attach user names to these rules. Role permissions should come through group memberships not through usernames!
If you have userLevel claim active on ESA and ESM does not use group attribute to determine if you are admin / normal user / read-only user, then it is no longer possible to manually assign ESM Roles to a Person in the solution.
All role relationships are strictly controlled by the groups provided by the IdP within the enabled realm.
Any role or access changes must be performed in the IdP, not in the solution.
How to configure ESA to assign ESM roles from AD
Login to ESA Admin console with Admin user (for example main.admin) using URL https://example.efectecloud.com/auth/admin
- Select correct realm from the top left dropdown menu
- Open
Clientssettings from the left side panel
- Select Client configuration (which ends with shibboleth) https://example.efectecloud.com/shibboleth
- Select
Client scopestab and select shibboleth link
- Select
Add mapperbutton and chooseBy configurationfrom dropdown
- Select option
SAML Efecte ESM userLevel mapperand add names and SAML Attribute Nameformat as in picture below (com:efecte:esm:userLevel & Unspecified). Save the changes.
Note that If customer is not using default groups ESMAdmins, ESMUsers, ESMreaders then the groups names must be changed in ESA host. Contact Matrix42 for configuration.
- Configure com:efecte:esm:roles mapper by adding new mapper By Configuration
- Select option SAML Efecte ESM roles mapper [Realm name] and add names and SAML Attribute Nameformat as in picture below (com:efecte:esm:roles & Unspecified). Save the changes.
- Go to ESM. In the ESM's Role Permission, every permission has an attribute "External identifier" - it should be set to be the name of the system/directory group.
Enable Unmanaged Attributes
Enable Unmanaged Attributes setting, otherwise you can't see Attributes-tab on Users page on Secure Access.
https://docs.efecte.com/faqs/user-details-attributes-tab-is-not-shown-in-esa-admin
How to configure ESA to assign ESM roles from Entra ID (previously Azure AD)
Prerequisite: Groups claim is configured to Entra ID (Groups are sent from Entra ID to ESA), both SAML and OIDC are supported. Guidance for OIDC: OIDC customer instructions and for SAML SAML customer instructions
1. Login to ESA Admin console with Admin user (for example main.admin) using URL https://example.efectecloud.com/auth/admin
2. Select correct realm from the top left dropdown menu
3. Add Groups mapper into Identity providers settings.
You need to add different attribute name based on your authentication type SAML or OIDC. Go to your Identity provider, and to mappers-tab. This groups claim (information) is not coming as default from Entra, so check that customer has configured this groups claim to Entra according to prerequisite guidance. For OIDC: OIDC customer instructions and for SAML SAML customer instructions
3A. For SAML use attribute name: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups sync mode override: Force, Claim: groups
3B. For OIDC use attribute name: groups sync mode override: Force, Claim: groups
4. After that Open Clients settings from the left side panel
5. Select Client configuration (ends with shibboleth) https://example.efectecloud.com/shibboleth
6. Select Client scopes tab and select shibboleth link (link contains shibboleth word)
7. Select Add mapper button and choose By configuration from dropdown
8. Select option SAML Efecte ESM userLevel mapper and add names and SAML Attribute Nameformat as in picture below (com:efecte:esm:userLevel & Unspecified). Save the changes.
Note that If customer is not using default groups ESMAdmins, ESMUsers, ESMreaders then the groups names must be changed in ESA host. Contact Matrix42 for configuration.
9. Configure com:efecte:esm:roles mapper by adding new mapper with By Configuration selection
10. Select option SAML Efecte ESM roles mapper [Realm name] and add names and SAML Attribute Nameformat as in picture below (com:efecte:esm:roles & Unspecified). Save the changes.
11. To connect ESM roles with Entra ID Groups - use External Identifier on ESM's role configuration screen:
Note: This should be the ObjectGUID of the group or group name of the Entra ID group - depending how it is configured for group claims.
Enable Unmanaged Attributes
Enable Unmanaged Attributes setting, otherwise you can't see Attributes-tab on Users page on Secure Access.
https://docs.efecte.com/faqs/user-details-attributes-tab-is-not-shown-in-esa-admin
Troubleshooting
Saml Extension for the browser
SAML extension (SAML decoder) for the browser is helpful when debugging the login.
The SAML decoders are available as browser extensions (e. g. SAML Tracer for Firefox, SAML Chrome Panel for Google Chrome). For example: https://addons.mozilla.org/en-US/firefox/addon/saml-message-decoder-extension/ or https://addons.mozilla.org/nl/firefox/addon/saml-tracer/
Logs
If ESA login works but ESM login not
- Check the ESM log called itsm.log (Efecte ESM→ Maintenance→Logs→Download logs→itsm.log)
If ESA login is not working
- Check the ESA's server.log (opt/keycloak/standalone/log/server.log)
- Check the ESA's container log /opt/keycloak/logs/keycloak.log
More info about Custom javascript mappers: https://docs.efecte.com/internal-configuration-instructions/1812412-esa-custom-javascript-mappers
Secure Access admin Users Attributes tab is not visible
Enable Unmanaged Attributes setting, otherwise you can't see Attributes-tab on Users page on Secure Access.
https://docs.efecte.com/faqs/user-details-attributes-tab-is-not-shown-in-esa-admin
Table of Contents