Note
LDAP authentication is a feature specific to Enterprise-level license holders. You must have an active enterprise license before beginning the configuration process. Additionally, if the LDAP server you want to connect to has a certificate that is self-signed or signed by a corporate internal certificate authority (CA), the CA certificate must be added to the system’s trusted CAs. Otherwise, connection to the LDAP server will result in an error that the certificate issuer is not recognized.
Administrators use LDAP as a source for account authentication information for Tower users. User authentication is provided, but not the synchronization of user permissions and credentials. Organization membership (as well as the organization admin) and team memberships can be synchronized.
When so configured, a user who logs in with an LDAP username and password automatically gets a Tower account created for them and they can be automatically placed into organizations as either regular users or organization administrators.
Users created via an LDAP login cannot change their username, first name, last name, or set a local password for themselves. This is also tunable to restrict editing of other field names.
To configure LDAP integration for Tower:
ldapsearch
command, which is a command line tool that can be installed on the tower system’s command line as well as on other Linux and OSX systems. Use the following command to query the ldap server, where josie and Josie4Cloud are replaced by attributes that work for your setup:ldapsearch -x -H ldap://win -D "CN=josie,CN=Users,DC=website,DC=com" -b "dc=website,dc=com" -w Josie4Cloud
Here CN=josie,CN=users,DC=website,DC=com
is the Distinguished Name of the connecting user.
Note
The ldapsearch
utility is not automatically pre-installed with Ansible Tower, however, you can install it from the openldap-clients
package.
The Authentication tab displays initially by default.
Note
Starting with Ansible Tower 3.3, you can configure multiple LDAP servers by specifying the server to configure (otherwise, leave the server at Default):
The equivalent API endpoints will show AUTH_LDAP_*
repeated: AUTH_LDAP_1_*
, AUTH_LDAP_2_*
, ..., AUTH_LDAP_5_*
to denote server designations.
Note
If the LDAP server you want to connect to has a certificate that is self-signed or signed by a corporate internal certificate authority (CA), the CA certificate must be added to the system’s trusted CAs. Otherwise, connection to the LDAP server will result in an error that the certificate issuer is not recognized.
CN=josie,CN=users,DC=website,DC=com
:sAMAccountName
, the LDAP User DN Template populates with (sAMAccountName=%(user)s)
. Active Directory stores the username to sAMAccountName
. Similarly, for OpenLDAP, the key is uid
–hence the line becomes (uid=%(user)s)
.LDAP Group Types include:
PosixGroupType
GroupOfNamesType
GroupOfUniqueNamesType
ActiveDirectoryGroupType
OrganizationalRoleGroupType
MemberDNGroupType
NISGroupType
NestedGroupOfNamesType
NestedGroupOfUniqueNamesType
NestedActiveDirectoryGroupType
NestedOrganizationalRoleGroupType
NestedMemberDNGroupType
PosixUIDGroupType
The LDAP Group Types that are supported by Tower leverage the underlying django-auth-ldap library.
Each LDAP Group Type can potentially take different parameters. Tower exposes
LDAP_GROUP_TYPE_PARAMS
to account for this.LDAP_GROUP_TYPE_PARAMS
is a dictionary, which will be converted by Tower to kwargs and passed to the LDAP Group Type class selected. There are two common parameters used by any of the LDAP Group Type;name_attr
andmember_attr
. Wherename_attr
defaults tocn
andmember_addr
defaults tomember
:{'name_attr': 'cn', 'member_attr': 'member'}To determine what parameters a specific LDAP Group Type expects. refer to the django_auth_ldap documentation around the classes
init
parameters.
CN=Tower Users,OU=Users,DC=website,DC=com
[
"OU=Users,DC=website,DC=com",
"SCOPE_SUBTREE",
"(cn=%(user)s)"
]
The first line specifies where to search for users in the LDAP tree. In the above example, the users are searched recursively starting from DC=website,DC=com
.
The second line specifies the scope where the users should be searched:
- SCOPE_BASE: This value is used to indicate searching only the entry at the base DN, resulting in only that entry being returned
- SCOPE_ONELEVEL: This value is used to indicate searching all entries one level under the base DN - but not including the base DN and not including any entries under that one level under the base DN.
- SCOPE_SUBTREE: This value is used to indicate searching of all entries at all levels under and including the specified base DN.
The third line specifies the key name where the user name is stored.
Note
For multiple search queries, the proper syntax is:
[
[
"OU=Users,DC=northamerica,DC=acme,DC=com",
"SCOPE_SUBTREE",
"(sAMAccountName=%(user)s)"
],
[
"OU=Users,DC=apac,DC=corp,DC=com",
"SCOPE_SUBTREE",
"(sAMAccountName=%(user)s)"
],
[
"OU=Users,DC=emea,DC=corp,DC=com",
"SCOPE_SUBTREE",
"(sAMAccountName=%(user)s)"
]
]
[
"dc=example,dc=com",
"SCOPE_SUBTREE",
"(objectClass=group)"
]
objectclass
of a group object is in the LDAP you are using.{
"first_name": "givenName",
"last_name": "sn",
"email": "mail"
}
The above example retrieves users by last name from the key sn
. You can use the same LDAP query for the user to figure out what keys they are stored under.
{
"is_superuser": "cn=superusers,ou=groups,dc=website,dc=com",
"is_system_auditor": "cn=auditors,ou=groups,dc=website,dc=com"
}
The above example retrieves users who are flagged as superusers or as auditor in their profile.
With these values entered on this form, you can now make a successful authentication with LDAP.
Note
Tower does not actively sync users, but they are created during their initial login.
Active Directory uses “referrals” in case the queried object is not available in its database. It has been noted that this does not work properly with the django LDAP client and, most of the time, it helps to disable referrals. Disable LDAP referrals by adding the following lines to your /etc/tower/conf.d/custom.py
file:
AUTH_LDAP_GLOBAL_OPTIONS = {
ldap.OPT_REFERRALS: False,
}
Note
“Referrals” are disabled by default in Ansible Tower version 2.4.3 and above. If you are running an earlier version of Tower, you should consider adding this parameter to your configuration file.
For details on completing the mapping fields, see LDAP Organization and Team Mapping.
To enable logging for LDAP, you must set the level to DEBUG
in the LDAP configuration file, /etc/tower/conf.d/custom.py
:
LOGGING['handlers']['tower_warnings']['level'] = 'DEBUG'
Next, you will need to control which users are placed into which Tower organizations based on LDAP attributes (mapping out between your organization admins/users and LDAP groups).
Keys are organization names. Organizations will be created if not present. Values are dictionaries defining the options for each organization’s membership. For each organization, it is possible to specify what groups are automatically users of the organization and also what groups can administer the organization.
users: None, True/False, string or list/tuple of strings. Same rules apply as for admins.
remove_users: True/False. Defaults to False. Same rules apply as remove_admins.
{
"LDAP Organization": {
"admins": "cn=engineering_admins,ou=groups,dc=example,dc=com",
"remove_admins": false,
"users": [
"cn=engineering,ou=groups,dc=example,dc=com",
"cn=sales,ou=groups,dc=example,dc=com",
"cn=it,ou=groups,dc=example,dc=com"
],
"remove_users": false
},
"LDAP Organization 2": {
"admins": [
"cn=Administrators,cn=Builtin,dc=example,dc=com"
],
"remove_admins": false,
"users": true,
"remove_users": false
}
}
Mapping between team members (users) and LDAP groups. Keys are team names (will be created if not present). Values are dictionaries of options for each team’s membership, where each can contain the following parameters:
users: None, True/False, string or list/tuple of strings.
- If None, team members will not be updated.
- If True/False, all LDAP users will be added/removed as team members.
- If a string or list of strings, specifies the group DN(s). User will be added as a team member if the user is a member of ANY of these groups.
remove: True/False. Defaults to False. When True, a user who is not a member of the given groups will be removed from the team.
{
"LDAP Engineering": {
"organization": "LDAP Organization",
"users": "cn=engineering,ou=groups,dc=example,dc=com",
"remove": true
},
"LDAP IT": {
"organization": "LDAP Organization",
"users": "cn=it,ou=groups,dc=example,dc=com",
"remove": true
},
"LDAP Sales": {
"organization": "LDAP Organization",
"users": "cn=sales,ou=groups,dc=example,dc=com",
"remove": true
}
}