22. Setting up LDAP Authentication¶

Note

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.

5. Enter the LDAP server address to connect to in the LDAP Server URI field using the same format as the one shown in the text field. Below is an example:

6. Enter the Distinguished Name in the LDAP Bind DN text field to specify the user that Tower uses to connect (Bind) to the LDAP server. Below uses the example, CN=josie,CN=users,DC=website,DC=com:

7. Enter the password to use for the Binding user in the LDAP Bind Password text field. In this example, the password is ‘passme’:

8. If that name is stored in key 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).

9. Click to select a group type from the LDAP Group Type drop-down menu list.

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 and member_attr. Where name_attr defaults to cn and member_attr defaults to member:

{"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.

10. Enter the group distinguish name to allow users within that group to access Tower in the LDAP Require Group field, using the same format as the one shown in the text field. In this example, use: CN=Tower Users,OU=Users,DC=website,DC=com

11. Enter the group distinguish name to prevent users within that group to access Tower in the LDAP Deny Group field, using the same format as the one shown in the text field. In this example, leave the field blank.

12. The LDAP Start TLS is disabled by default. To enable TLS when the LDAP connection is not using SSL, click the toggle to ON.

13. Enter where to search for users while authenticating in the LDAP USER SEARCH field using the same format as the one shown in the text field. In this example, use:

[
"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)"
  ]
]

14. In the LDAP Group Search text field, specify which groups should be searched and how to search them. In this example, use:

 [
"dc=example,dc=com",
"SCOPE_SUBTREE",
"(objectClass=group)"
 ]

• The first line specifies the BASE DN where the groups should be searched.

• The second lines specifies the scope and is the same as that for the user directive.

• The third line specifies what the objectclass of a group object is in the LDAP you are using.

15. Enter the user attributes in the LDAP User Attribute Map the text field. In this example, use:

{
"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.

16. Enter the user profile flags in the LDAP User Flags by Group the text field. In this example, use the following syntax to set LDAP users as “Superusers” and “Auditors”:

{
"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.

17. For details on completing the mapping fields, see LDAP Organization and Team Mapping.

18. Click Save when done.

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. To improve performance associated with LDAP authentication, see ug_ldap_auth_perf_tips in the Ansible Tower User Guide.

22.1. Referrals¶

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.

22.2. Enabling Logging for LDAP¶

To enable logging for LDAP, you must set the level to DEBUG in the Tower Settings configuration window:

1. Click the Settings () icon from the left navigation pane and select System.

2. From the System configuration page, click the Logging tab.

3. Scroll down to the bottom and set the Logging Aggregator Level Threshold field to Debug.

4. Click Save to save your changes.

22.3. LDAP Organization and Team Mapping¶

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.

admins: None, True/False, string or list/tuple of strings.

• If None, organization admins will not be updated based on LDAP values.

• If True, all users in LDAP will automatically be added as admins of the organization.

• If False, no LDAP users will be automatically added as admins of the organiation.

• If a string or list of strings, specifies the group DN(s) that will be added of the organization if they match any of the specified groups.

remove_admins: True/False. Defaults to False.

• When True, a user who is not an member of the given groups will be removed from the organization’s administrative list.

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:

organization: string. The name of the organization to which the team

belongs. The team will be created if the combination of organization and team name does not exist. The organization will first be created if it does not exist.

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
}
}