This article has been superseded by Entuity v21.0. To view the latest information on this topic, please see this article.
To set up internal authentication
To set up external authentication via LDAP
Example of alternative DN construction
To configure LDAP group search
To map LDAP groups to Entuity user groups
To configure LDAP server location and security
Entuity recommendations for external authentication
Note for ENA v18.0 upwards
To configure user access to Entuity servers
To change password for LDAP login
Troubleshooting and testing external authentication through emergency user accounts
You can control access to Entuity in one of two ways:
- internal user authentication through its own security database.
- external user authentication through integrating Entuity user groups and names within the LDAP or RSSO environments.
To set up internal authentication:
By default, Entuity holds its user authentication details in its local security database.
When you install multiple Entuity servers with internal authentication, each Entuity server maintains its own user accounts, user groups and user preferences.
This independence allows user accounts and groups on different servers to share the same names, but have different definitions.
Internal authentication allows for:
- definition of user accounts on the local server. User sign-on details are compared with the details held for that account in the Entuity server's local security database.
- assignment of users to Entuity user groups. User groups are used in user authorization - when determining whether a user has the appropriate permission to perform the requested action.
- retention of user preferences between sessions.
To set up external authentication via LDAP:
You can integrate Entuity servers into environments where LDAP authentication systems are already implemented. External authentication compares user sign-on details with the account details held in the external authentication system (LDAP). External authentication can work with a single Entuity server and multiple Entuity servers running local security databases.
- In the Main Menu, click Administration.
- Click Account Management.
- Under the LDAP Settings section, click Add. This opens the LDAP Management page.
- There are 3 tabs on this page which you navigate to by clicking Next, and you can Test the settings of each tab:
- Server Details.
- Group Searching.
- Group Mapping.
The first tab on this page is the Server Details tab. Here you can specify the connection details Entuity requires to connect to the LDAP server.
- In order to quickly find a user in LDAP, you need to know which attribute and base DN you can use to match the user that is trying to log in.
- When a user is logging in using a fully-qualified name (e.g. john.doe@entuity.com), Entuity will pass 3 arguments to LDAP:
- login name entered in the login screen (john.doe@entuity.com).
- name only (john.doe).
- domain name (entuity.com).
- You can access each of these in the search mapping as {0}, {1}, and {2}.
- If the server type is Windows AD, the attribute is hardcoded to "cn", and the search pattern will be mapped as follows:
- (cn={1}) if there is no domain, otherwise (cn={1}@{2})
- If the server type is Open LDAP, you can specify an attribute, and the search pattern will be mapped as follows:
- (ATTR_ID={1}), with the ATTR_ID being specified in the configuration.
- Specify the type of authentication server in the Server Type field, either Windows AD or OpenLDAP/LDAPv3.
- Enter the name of the authentication server as displayed in Entuity in the Display Name field.
- Enter the IP address or resolved name of the authenticating LDAP server in the IP Address/Host Name field.
- Enter the port used by the LDAP server in the Port field. This is not required if using the default (which is 389, or for SSL 636).
- In the Bind Username as DN field, select Yes if your LDAP server only supports the bind operation using the DN format and you cannot construct a valid user DN using Entuity's expression formats. Selecting No will mean Entuity searches the LDAP server for the username.
- Enter the user account and password needed to access the LDAP server in the Lookup User Account and Lookup User Password fields. These are not necessary if the server supports anonymous login.
- Enter the starting point for searches in the LDAP directory in the Base DN field.
- Enter the domain name to use as the search base in the Domain Name field. This attribute only applies to Windows AD.
- Enter your preferred user search filter in the User Search Filter field. This field only applies when Bind Username as DN is set to No. This filter restricts the search to the user class and then compares the value to the sAMAccountName attribute.
- Specify your method of encrypting an LDAP connection in the Using SSL/TLS field. Choose No when not using TLS, LDAPS to use SSL, or Start TLS when using TLS.
Click Next to access the second tab on this page, which is the Group Searching tab. On this tab, you can specify the LDAP filter expression for performing the group search.
-
In order to quickly find a group in LDAP, Entuity will pass 4 arguments to LDAP:
- login name entered in the login screen (john.doe@entuity.com).
- name only (john.doe).
- domain name (entuity.com).
- user DN that is returned by LDAP after a successful bind.
- You can access each of these in the search mapping as {0}, {1}, {2} and {3}
- By default, the group search is mapped to (GROUP_MEMBER_ATTRIBUTE={3})
- In the User Refers to Groups field, select Yes so that Entuity searches for groups using the user's MemberOf attribute. Select No so that Entuity searches for groups based on Group Base DN and then which group's member contains the user.
- Enter the OpenLDAP/LDAPv3 attribute that sets how to search the groups in the Group Name Attribute field.
- Enter the domain base from which you search for groups in the Group Base DN field. If left empty, the search uses Base DN.
- Enter the group search filter in the Group Search Filter field. This only applies when User Refers to Groups is set to No.
- Specify the numbers of levels of parent groups a search will go, if the group is not found in the current parent group, in the Search Parent Groups (levels) field.
- Specify whether you want search to search for the group within all nested sub-groups in the Search Nested Groups field.
Click Next to access the third tab on this page, which is the Group Mapping tab. On this tab, you can map the user groups defined in Entuity to those groups defined on the LDAP server.
- Under the Group Mapping Policies section is a table listing all of the local groups defined on the Entuity server. You can sort the columns into ascending or descending order by clicking on the column heading.
- The local groups are listed under the Local Groups column. In the Mapped Users/Groups column, you will see one of the following:
- Complex XML Content - indicates security.config.xml has been directly edited and contains more complex conditions than the web UI can support.
- U:userName, G:groupName - indicates LDAP user accounts and groups associated with the Entuity group.
- All Users - indicates all LDAP users are mapped to the Entuity user group.
- Empty - there are no mapped LDAP users or user groups.
You can directly edit the security file when building more complex mappings. For example, the following mapping:
Administrators U:RiLee G:Supervisors
associates the Administrators group with user RiLee and the Supervisors user group. This is an additive relationship - for RiLee to login he must be a member of the Supervisors group. If you want to allow RiLee or any member of the Supervisors group access to Entuity, then you must amend the security configuration file:
<condition>
<or>
<attr name="userName" containes="RiLee"/>
<attr name="groups" contains="Supervisors" />
</or>
</condition>
- Under the Server Access Policies section, you can select how access to the Entuity server is controlled (if instead you want to specify server access at the server level, please see the section below). Select either:
- Allow Access for All Users - permit access to all users.
-
Allow Access for Specific Users/Groups - allow access to only specified users and user groups.
When you view the XML, the first rule is to deny access to all users. Subsequent rules specify the exceptions:
<serverAccess>
<denyUserDomain="*" name="*">
<allowUserDomain="*" name="RiLee">
</serverAccess>
- Once you have specified these parameters, click OK at the bottom of the browser to complete the LDAP authentication, otherwise click Cancel.
- Tick the Enable Emergency User box if you want to make the emergency user account available. This would be used when Entuity cannot communicate with an LDAP server. Please see the article on emergency user account management for further help and information on this concept.
- Tick the Multiple Repositories Mode box if you want Entuity to continue authenticating against other servers, even if a previous server reported an authentication failure. This enables you to have multiple LDAP servers with potentially differing sets of accounts. If left unticked (which is the default), Entuity stops at the first server that it can connect to and the authentication result will be from this server (whether it is successful or not). This is in case you have mirrored LDAP servers for high availability.
- You will then need to click Apply LDAP Settings at the bottom of the Account Management page.
- This will open the Apply Settings window. Click Yes to enter your user account credentials to ensure you can log in with the new settings. If the user test is successful, the Entuity server will restart and apply the new settings.
Entuity creates an XML file to hold the authentication details - entuity_home/etc/security.config.xml.
- to create a more complex authentication configuration than is possible through the Entuity UI you can directly edit security.config.xml.
- to propagate the same configuration across multiple Entuity servers, you can copy security.config.xml from a configured server to all other servers. You must still configure the appropriate user groups on each server.
Note, when Entuity is configured for external authentication, you will need to add the following to the [lcm] section in entuity.cfg, in order to resolve the error 'No permission to execute this task' when running Config Mgmt. The specified user must be a member of the local admins group:
[lcm]
defaultAdminUser=newAdmin
Advanced LDAP authentication:
When configuring Entuity for use with LDAP, consider whether you want users to log on entering:
- only the username.
- both the user and domain names.
Entuity recommends enforcing domain name usage when allowing users from different domains to log in. Entuity LDAP:
- supports the User Principal Name (UPN) format, i.e. username@domain.
- does not support the Universal Naming Convention (UNC) format, i.e. \\domain\username and domain\username.
From the user logon information, you must be able to construct the distinguished name (DN) of the user LDAP entry on the LDAP server. The bind name is constructed from information supplied when attempting to log on. You can specify how the bind name is constructed, and in what format, through the ldap-config module in security.config.xml in entuity_home/etc:
<userBindName>expression</userBindName>
<userBindNameIsDN>boolean</userBindNameIsDN>
where:
-
expression constructs the bind name. This can include fixed values as well as values supplied during the log on. There are three possible variables, represented as {0}, {1} and {2}. These variables are replaced with values taken from the logon:
- {0}, is the entered logon name, which could include both username and domain.
- {1}, is the username part of the logon.
- {2} replaced with domain part of the logon (may be empty).
- boolean indicates whether the constructed bind name includes a domain name (true), or not (false).
When constructed, the bind name is used to authenticate (bind) against the LDAP server (together with the entered password). If the bind operation succeeds, then the user is authenticated and the login accepted, otherwise the login attempt is rejected and fails.
Example of alternative DN construction:
If your LDAP server only supports the bind operation using the DN format, and you cannot construct a valid user DN using Entuity's expression formats, you can configure Entuity to use an alternative approach to authenticate the user:
- The connection to the LDAP server is made with the system user name and password specified in the configuration file (this user must have enough privileges to search the directory in the specified location).
- A search for the user entry is made on the basis of the supplied criteria.
- If the user entry is:
- located, the DN of that entry is used to bind against LDAP.
- not found, or the bind operation fails then the log on fails.
You configure these options in the ldap-config module in security.config.xml:
<lookupUserBindDNAsSystemUser>true</lookupUserBindDNAAsSystemUser>
<userSearchBaseCtxDN>
dc=example, dc=com
</userSearchBaseCtxDN>
<userMatchFilter>
(userPrincipalName={1}@{2})
</userMatchFilter>
<systemUserName>
cn=userwithsearchpriveleges, dc=example, dc=com
</systemUserName>
<systemUserPwd>password</systemUserPwd>
where:
-
LookupUserBindDNAsSystemUser when set to:
- true, sets the requirement to find the user’s DN before trying to bind as that user.
- false, assumes you can construct a valid DN from the logon details.
- userSearchBaseCtxDN defines the search directory sub-tree.
- userMatchFilter is the criteria on which the user is identified.
- systemUserName is the used connect details, user name and password.
This example equates to:
- A connection using username="cn=userwithsearchprivilieges, dc=example, dc=com"
and password = "password" - A directory path of dc=example, dc=co
- A search of the sub-tree for the entry whose attribute userPrincipalName equals
username@domain. - When the search finds:
- a single entry, the bind operation uses the DN of that entry.
- no matching entry the log on attempt fails.
- multiple entries, the log on attempt fails and logs indicate an incorrect configuration.
To configure LDAP group search:
When a successful user authentication (bind) operation completes, the next stage is identifying that user’s groups on the LDAP server. Identification requires the user’s DN, so where user authentication was through UPN it must be derived. This example section derives user DN:
<userBindName>{1}@{2}</userBindName>
<userBindNameIsDN>false</userBindNameIsDN>
<lookupUserBindDNAsSystemUser>false</lookupUserBindDNAsSystemUser>
<userSearchBaseCtxDN>
dc=example, dc=com
</userSearchBaseCtxDN>
<userMatchFilter>>
{userPrincipalName={1}@{2})
</userMatchFilter>
where:
- userBindNameIsDN is false, indicating the bind name is in UPN format
-
lookupUserBindDNAsSystemUser is:
- false, indicating the DN search is for the current user who has sufficient privileges to search the specified folder sub-tree.
- true, indicating the search should use the privileges of the system user.
- userPrincipalName the UPN format name on which the DN lookup is performed.
After the LDAP server finds the user’s DN, it then searches for the user’s groups. The search requires access to the relevant folders on the LDAP server. When the authenticated user does not have access you can specify whether group search must be done with system user:
<searchGroupsAsSystemUser>true</searchGroupsAsSystemUser>
Set searchGroupsAsSystemUser to:
-
false when the authenticated user has the access rights to search the LDAP server for
their groups. -
true when the authenticated user in your LDAP server does not have enough permissions
to search for the groups. You must then provide system user name and password, using
systemUserName and systemUserPwd.
This configuration indicates the user entry in the LDAP server contains attributes that list all distinguished names of the groups to which the user belongs, and all of these group entries contain an attribute to indicate to which group they belong (groups could be members of groups):
<userRefersToGroup>true</userRefersToGroup>
<userMemberOfAttrID>memberOf</userMemberOfAttrID>
<groupNameAttriID>cn</groupNameAttrID>
where:
-
userRefersToGroup is:
- true, indicating the user has an attribute which refer to groups this entry is member of.
- false, indicating the user entry does not contain a reference to the member’s group.
- userMemberOfAttrID is the attribute that identifies member groups.
-
groupNameAttrID is the name on the group attribute which identifies the group name, e.g.
cn.
All groups specified are navigated recursively, returning all group names to which the user belongs. Where the user entry does not contain a reference to the groups it is a member of, you must use take another approach. The LDAP server can recursively search for groups that refer to the user as a member, as well as groups that refer to other user groups.
This configuration indicates the user entry on the LDAP server does not have any information on group membership, but instead group entry refers to member users or groups (or group members of groups):
<userRefersToGroup>fales</userRefersToGroup>
<groupSearchBaseCtxDN>
DC=example, DC=com
</groupSearchBaseCtxDN>
<groupMatchFilter>(member={3})</groupMatchFilter>
<groupSearchDepth>5</groupSearchDepth>
<groupNameAttrID>cn</groupNameAttrID>
where:
-
userRefersToGroup is:
- true, indicating the user has an attribute which refer to groups this entry is member of.
- false, indicating the user entry does not contain a reference to the member’s group.
- groupSearchBaseCtxDN specifies the directory path of the sub-tree where group entries could be located.
- groupMatchFilter specifies the matching criteria for a group to be considered as group for the user or group. The match can use variables, including {3} which is replaced by the distinguished name of the user or the group, for whom we are searching the group.
- groupSearchDepth sets the group recursion depth. Only increase this value when your LDAP schema has more levels of memberships.
-
groupNameAttrID is the name on the group attribute which identifies the group name, e.g.
cn.
To map LDAP groups to Entuity user groups:
When the user has been authenticated and their groups retrieved from the LDAP server, this information (attributes) must be mapped to Entuity user groups. Through the ExternalAttributesMapping module you must define rules that map LDAP retrieved user groups to Entuity groups.
There are two types of rules: revoke and grant. Each rule may have a list of groups to which membership is granted or revoked. You can apply the rule unconditionally, or specify conditions so the rule only applies to groups that meet the set criteria.
The rules are applied in the order specified in the configuration. Rules can also be impacted by the case sensitivity of evaluated data, in environments where casing is not important use the ignorecase attribute. ignorecase applies to the user logon details as well as the retrieved attribute details.
After LDAP authentication, mapping rules can be built using these attributes:
-
logonName, the user logon details, which includes the username and where entered the
domain name. - userName, the user logon name only.
- domainName, the domain name only, if entered when the user logged on.
- groups, names of the groups on the external authentication system.
revoke and grant rules have the same structure. The following example shows grant:
<grant name="ruleName">
<group name="MyEntuityGroup1"/>
<group name="MyEntuityGroup2"/>
<condition>
...
</condition>
</grant>
where:
- grant is the rule type (the other rule type is revoke).
- name is the name of the rule, its use is optional but Entuity recommends its use to improve the readability of your configuration.
- group is the name of the user group affected by the rule.
- condition specifies the tests against which the received data is evaluated. It returns either true or false.
grant and revoke rules are used to map an authenticated user’s LDAP groups to user groups, and therefore assign them permissions. Within grant and revoke rules, you can specify conditions that are tested against the LDAP groups, and only when the condition is true are the user groups specified in the rule associated to the user.
Rule conditions contain attribute values that are used as test expressions These expressions can be combined using standard Boolean logic operators, AND, OR, NOT.
An attribute test expression has the structure:
<attr name="attrName" contains="attrValue"/>
where:
- attr indicates this is an attribute clause.
- name is the attribute name.
- contains is the test attribute value. When the named attribute contains this value the expression is considered true.
By combining these expressions with boolean operators, you can increase the sophistication of the condition. The following example is a grant rule, which when true maps the Administrators group to the user:
<grant name="Local users groups">
<group name="administrators" />
<condition>
<or>
<attr name="userName" contains="rootAdmin"/>
<attr name="userName" contains="sysAdmin"/>
<attr name="userName" contains="seniorAdmin"/>
<and>
<attr name="groups" contains="seniorAnalysts" />
<attr name="groups" contains="seniorNetAdmins" />
<attr name="groups" contains="seniorNetSupport" />
</and>
</or>
</condition>
</grant>
The condition tests whether the user is:
- the rootAdmin user.
- the sysAdmin user.
- the seniorAdmin user.
- a member of all of the listed groups, seniorAnalysts, seniorNetAdmins and
seniorNetSupport groups.
When one of these tests is:
-
true, the condition is set to true and the user is associated to the Administrators
group. - false, the user is not associated to the Administrators group.
To configure LDAP server location and security:
The LDAP server location is configured through the ldap-config module in security.config.xml. You can specify the protocol used when connecting to the LDAP server, facilitating a normal or secure (SSL) connection. This has the format:
<property name="java.naming.provider.url" value="ldap://host:port" />
where:
- property name identifies the location as a Java URL. This should not be amended.
-
value is the LDAP server URL which can include the server’s port, for example:
ldaps://myhost
ldap://myhost:12345
Entuity recommendations for external authentication:
- Decide if you are to use internal or external authentication as early as possible in your deployment. Switching to external authentication later in the deployment can introduce issues.
- In an LDAP-integrated external authentication system, do not allow access to users who do not have relevant group membership, unless there is a good reason to do so.
- Decide the required user groups early in the deployment, and set up the necessary permissions on all servers.
- Allocate a service account at the start of the installation, and use it for administrative changes, e.g. creating Views, EMS changes and integration configurations where a user account needs to beh provided.
Note for ENA v18.0 upwards:
When configured for external authentication via LDAPs, ENA v18.0 upwards enforces hostname verification between certificates and the LDAP server. If your LDAP TLS certificates are non-compliant with hostname verification, then the LDAPs intgrations will stop working after installing ENA v18.0.
Entuity recommend that users plan for new certificates before upgrading to ENA v18.0. If you are unable to rebuild certificates, Entuity recommend that you contact Entuity Support for details of how to handle non-compliant certifications.
To configure user access to Entuity servers:
Within multiple Entuity server installations, you may want to configure access permissions at the Entuity server level, rather than at the authentication service level. For example, you may want a user to have full access to one Entuity server but more restricted access to another Entuity server.
You can set rules to specify user and group access through the ServerAccess module in security.config.xml. By having different ServerAccess module definitions on different servers, you can define different user and group permissions. There are 4 rule types that are evaluated against submitted attributes:
- allowUser - allows user access to the server by comparing to the rule value the user’s username, domain values or both.
- denyUser - denies user access to the server by comparing to the rule value the user’s username, domain values or both.
- allowGroup - allows user access to the server by comparing to the rule value the user’s group membership.
- denyGroup - denies user access to the server by comparing to the rule value the user’s group membership.
allowUser and denyUser rules have the following structure:
<ruleName name="*" domain="*"/>
where:
- ruleName can be allowUser or denyUser
-
name is the user name:
- * indicates all users, and is the default value.
- user name is the user name.
-
domain is only applicable with external authentication. It is the domain associated with the network user account:
- * indicates all domains, and is the default value.
- domain name is the user’s network domain name.
When both parameter name and domain are specified in the allowUser and denyUser rules, then the rule is only matched when both parameter values are matched (logical AND).
allowGroup and denyGroup rules have the following structure:
<ruleName name="*"/>
where:
- ruleName can be allowGroup and denyGroup
-
name is the user group name:
- * indicates the rule applies to all groups, and is the default value.
- name is the group name.
Rule evaluation can be either case sensitive or case insensitive, which is specified through the ignorecase attribute of the serverAccess element:
<serverAccess ignorecase="true">
To test server access configuration:
You can test server access configuration rules using authtool, which has the structure:
authtool serverAccess [user=username] [groups=list_of_groups]
where:
- authtool is the authentication tool which you can run from the command line to test your security configuration.
- serverAccess identifies the security module you are testing.
- user is the Entuity user.
- groups is one or more user groups against which the rules are applied. A list of groups would be enclosed in quotation and comma delimited.
To change password for LDAP logins:
Applicable for ENA v17.0 P05 upwards
From ENA v17.0 P05 upwards, LDAP users can change their password through the account administration page as they would if they were authenticated internally. Entuity will forward the request to the LDAP server.
When the password has expired, the user will be prompted to change their password upon login. Note, the password complexity rules specified for internal users will not be enforced for LDAP passwords, and must be configured on the LDAP server itself. LDAP servers can create their own password complexity, and there may be a conflict if they are different.
Troubleshooting and testing external authentication through emergency user accounts:
When Entuity uses an external authentication server, access to Entuity is limited if the authentication server is unavailable. Entuity includes a special emergency access user account which does not require external authentication and can be used when the authentication server fails. This account is maintained through authtool.
Please see this article for further help and information on emergency user accounts.
Comments
0 comments
Please sign in to leave a comment.