Applicable to Entuity v19.0 P04 upwards
To integrate SAMLv2 with Entuity
To use the SAMLv2 integration with the BMC TrueSight Presentation server
Introduction:
From Entuity v19.0 P04 upwards, Entuity offers support for Security Assertion Markup Language 2.0 (SAMLv2) authentication. SAMLv2 is an XML-based protocol that uses security tokens containing assertions to pass information about an end user between a SAML authority (named an Identity Provider or IdP, e.g. Okta) and a SAML consumer (named a Service Provider, i.e. Entuity).
This enables web-based, cross-domain single sign on (SSO), and allows you to add SSO support to various identity providers.
Summary of method:
- A user tries to access a URL in the Entuity UI. Entuity receives a user's HTTP request against secured content and checks for a valid EOTSLOGIN cookie.
- If a valid cookie is not found, the user is redirected to the SAML IdP (e.g. Okta).
- After successful authentication, the IdP redirects the user back to Entuity with a signed assertion.
- Entuity validates SAML assertion and applies mapping rules, resulting in a set of Entuity groups to be assigned to the user. Entuity ensures the user (with group membership) is created/updated locally as well as on remote servers. The EOTSLOGIN cookie is created as well.
- Entuity then redirects the user to the original URL they tried to access. With a valid cookie present, the request will succeed.
Note on signing out:
During sign out, the user is only logged out from the Entuity session and is redirected to a simple informational page.
Although logged out of Entuity, the user is not necessarily signed off from the IdP's session, which means the user can access Entuity again (without needing to reauthenticate) by navigating to the required Entuity URL. The length of time for which the IdP's session will remain valid is vendor-specific.
To integrate SAMLv2 with Entuity:
The Entuity configuration with SAMLv2 requires configuration of both Entuity and the IdP:
- Entuity installation needs to be registered within the IdP, and users need to be given access to this Entuity installation.
- Entuity needs to be configured to trust the IdP. Entuity also needs to be configured with mapping rules that map IdP authentication assertion to a set of Entuity user groups.
1. IdP configuration:
This section uses Okta as an example of an IdP. Before configuring the IdP, you need to know the hostname of the Entuity installation, which is the hostname used by users to access the Entuity web UI.
This section is sufficient for configuring the IdP side of the integration.
Note, Okta provides fine-tuning options that you might find useful - please refer to the Okta documentaton for this.
- From the Main Menu, click Applications.
On the Applications page, click Create App Integration.
- In the Create a new app integration dialog, select SAML 2.0 and click Next.
- This will open the Create SAML Integration dialog. Under the General Settings tab, enter an App name of your preference. In this example, it is called ENA_MARCO.
- Under the Configure SAML tab:
- enter the Single sign on URL in the following format:
http://<Entuity hostname>/saml/SSO
e.g. http://marco/saml/SSO. If Entuity is configured for SSL (which is recommended), use 'https' instead of 'http'.
- enter the Audience URI (SP Entity ID) in the following format:
http://<Entuity hostname>/saml/metadata
e.g. http://marco/saml/metadata. If Entuity is configured for SSL, use 'https' instead of 'http'.
- You can optionally specify the Default RelayState. The default relay state specifies the URL to navigate to in case the user launches the application from within the Okta portal (or within ohter portals that embed the URL provided by Okta for this application. The default relay state is specified in the following format:
http://<Entuity hostname>/dashboard
e.g. http://marco/dashboard. If Entuity is configured for SSL, use 'https' instead of 'http'.
- You can optionally specify the Attribute Statements and Group Attribute Statements. If specified, the IdP will send these attributes to Entuity (after the user authentication). These attributes can be used by mapping rules within Entuity to resolve Entuity group names. If you do not specify these then the IdP will only send the username of the authenticated user, and mapping rules will need to be based on the username only.
The below example is only illustrative - you should use the attributes that best suit your own circumstances:
This sends the following attributes to Entuity:
- samlEmail - the value of the built-in user email attribute.
- samlUserType - the value of the custom user attribute called 'appUserType'.
- samlGroup - the set of all group names to which the user belongs within Okta. Note that any single attribute may have multiple values associated with it.
- enter the Single sign on URL in the following format:
- Click Next to progress to the Feedback tab. Under this tab, select the following options:
- I'm an Okta customer adding an internal app.
-
This is an internal app that we have created.
- Click Finish. This will take you to the page of the newly-created application.
- Under the Assignments tab of this page, click Assign to assign users/groups who are permitted to use Entuity (you can create user accounts under the directory menu in Okta).
- Under the Sign On tab of this page, click and download the 'Identity Provider metadata' XML file. This file will be needed during configuration of Entuity. You can save this file under a name of your choosing, but in this example it will be referred to as 'okta.metadata.xml'. Note, to ensure that Entuity can read this metadata.xml file, it needs to be is UTF 8 encoded.
2. Entuity configuration:
On the Entuity side, it is necessary to establish the IdP trust and configure group mappings.
Please note, if you are switching an Entuity installation from an existing, different authentication, you may lose access to some resources which have previously been owned by different user accounts.
-
Establish IdP trust:
- Copy the 'okta.metadata.xml' file to <ENTUITY_HOME>/etc/saml/directory.
- Add the following section to <ENTUITY_HOME>/etc/entuity.cfg. Note, replace <hostname> with the name of the Entuity server with which users access the web UI. This must match the hostname you have used to configure the IdP (in this example, the hostname is 'marco'). The file must be UTF 8 encoded.
[saml]
metadataFilePath=${ENTUITY_HOME}/etc/saml/okta.metadata.xml
publicHostname=<hostname>
-
Configure group mappings:
- Copy saml-groups-example.mapping to saml-groups.mapping within the <ENTUITY_HOME>/etc/saml directory. This file contains group mapping rules.
- Edit file that you have copied to suit your needs. The following example file includes documentation.
# Example groups mapping file
After the above steps, you can start (or restart) Entuity, and you can access it with the authentication step delegated to the IdP.
# The actual file from which rules are read needs to be named saml-groups.mapping
#
# Comments begin with the hash on their own line.
# File contains a collection of rules. Each rule consists of:
# - a header in a form of: rule = <name>
# - zero or more conditions, each condition is in a form: <attrName>.match = <regex pattern>
# - one or more group assignment statements in a form: group.assign = <group name>
#
# Group mapping works in a following manner:
# Each rule is applied to a SAML assertion (SAML assertion has a list of attributes and each attribute may have multiple values).
# If ALL the rule conditions match, then the user will be assigned specified groups (note, a rule without conditions apply unconditionally).
#
# Examples follow below. These should not be used as they are, but should be adapted to your particular environment.
# Let any user who can log in via SAML be assigned to 'All Users' group
rule = All Users Welcome
group.assign = All Users
# Match particular user to be admin
# nameId is the attribute which is present in all SAML assertions
rule = Head of IT Department
nameId.match = theboss@megacorp.com
group.assign = Administrators
# People who are the members of the certain SAML group will be assigned multiple Entuity groups
# samlGroup attribute (in the example below) need to be provided by the SAML identity provider via its configuration
rule = Santa Helpers
samlGroup.match = .*Elf.*
group.assign = Application Approval
group.assign = Assembly Line
# Match users from a customer from a specific domain who are also members of the specific group
rule = Big Name Customer
nameId.match = .*@bignamecustomer.com
samlGroup.match = .*IT Dept.*
group.assign = Big Name Customer
group.assign = Platinum Subscription
Note: any syntax error in the SAML group mappings file will cause all users to be locked out of the system.
-
Troubleshooting Group Mapping Rules:
You an increase log level to output the details of mapping rule evaluation, which happens during login to Entuity. Append the following line to the <ENTUITY_HOME>/etc/tomcat-log4j2.properties file:logger.SEC.name = com.entuity.security.service
The details are logged to the tomcatAll.log in the log directory.
logger.SEC.level = DEBUG
RESTful API:
The enhancements listed below are available in any authentication mode (whether it is SAML, RSSO, internal authentication or LDAP).
Access key authentication:
Alongside authenticating with a username and password by using the HTTP 'Authorization' header and 'Basic' scheme, you can authenticate with an access key.
The access key can be supplied in the HTTP request's ENA-Api-Key header. Note, if both the 'Authorization' header and the 'ENA-API-Key' are specified, the 'Authorization' header will take precedence and the access key is ignored.
Valid access keys are configured in <ENTUITY_HOME>/etc/accessKeys.properties file. Note, this file does not exist by default, and needs to be created by the administrator.
The format of the file is as follows:
- single-line comments begin with a hash # symbol.
- access keys are specified in the following format: <access_key> = <ena_username>, where:
- <access_key> should be a long string which is hard to guess, and should contain the following characters only:
- digits (0-9)
- lower case ASCII characters (a-z)
- upper case ASCII characters (A-Z)
- <ena_username> is the name of the existing Entuity account. HTTP requests which authenticate with the provided access key will be performed on behalf of this user.
- <access_key> should be a long string which is hard to guess, and should contain the following characters only:
Example accessKeys.properties:
# This is a comment
verystrongsecret = admin
anotherstrongsecret = user
For authentication with the access key to be successful, the 'ENA-Api-Key' header in the HTTP request must match one of the access keys specified in the file (case sensitive), and the user associated with the access key must already exit in Entuity.
User impersonation:
The RESTful API HTTP request may include 'ENA-Impersonated-User' header with a value of the existing Entuity username. If include, the request is executed on behalf of this user.
For impersonation to be successful, all the below conditions must hold (if not, the request will fail with an 'access denied' error):
- the authenticated user must be a member of the built-in 'Administrators' group.
- the username specified in the 'ENA-Impersonated-User' header must already exist within Entuity.
Debug agent access:
Entuity v21.0 P01 and below:
Access to the debug agent is based on the access keys created for the RESTful API. To log in to the debug agent, you will need to enter your username and use the access key for the password. This specific access mode is only available in SAML mode.
Entuity v21.0 P02 upwards:
As of Entuity v21.0 P02, the debug agent is only accessible in SAML mode via Access Tokens. Please see this article for help and information on using debug agent.
To use the SAMLv2 integration with the BMC TrueSight Presentation server:
To use the SAMLv2 integration with the BMC TrueSight Presentation Server, you must allow for SAML authentication to be performed inside the iframe. In Okta, this can be enabled by navigating to Settings > Customization > IFrame Embedding.
Comments
0 comments
Please sign in to leave a comment.