12. Setting up Authentication¶

12.1. Azure Active Directory (AD)¶

1. Create an organization-owned application at https://auth0.com/docs/connections/enterprise/azure-active-directory and obtain an OAuth2 key (Client ID) and secret (Client Secret). Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends.
2. Access the Configure Tower feature in the Ansible Tower User Interface to complete the procedure. For instructions, refer to the Tower Configuration section.
3. If not already pre-populated, provide the generated callback URL for your application through the Microsoft Azure portal from the first step.

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

For application registering basics in Azure AD, refer to: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-authentication-scenarios#basics-of-registering-an-application-in-azure-ad

4. Click Save when done.

12.2. Google OAuth2 Settings¶

1. Create a project at https://console.developers.google.com/ and obtain an OAuth2 key and secret for a web application.
2. If not already pre-populated, provide the following callback URL for your application, replacing “tower.example.com” with the FQDN to your Tower server: https://tower.example.com/sso/complete/google-oauth2/
3. Complete the procedure in the Ansible Tower User Interface. For instructions, refer to the Tower Configuration section.

Refer to the Python Social Auth documentation for advanced settings: https://python-social-auth.readthedocs.org/en/latest/backends/google.html#google-oauth2

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

4. Click Save when done.

12.3. Github OAuth2 Settings¶

1. Create a developer application at https://github.com/settings/developers and obtain an OAuth2 key (Client ID) and secret (Client Secret).
2. If not already pre-populated, provide the following callback URL for your application, replacing “tower.example.com” with the FQDN to your Tower server: https://tower.example.com/sso/complete/github/
3. Complete the procedure in the Ansible Tower User Interface. For instructions, refer to the Tower Configuration section.

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

4. Click Save when done.

12.4. SAML Authentication Settings¶

To setup SAML authentication:

1. Access the Configure Tower feature in the Ansible Tower User Interface. For instructions, refer to the Tower Configuration section.
2. You may optionally enter the URL for a domain name you own (does not need to be a valid URL as this value is only used as a unique ID) in the SAML Service Provider Entity ID field.
3. Create a keypair for Tower to use as a service provider (SP) and include the certificate and private key contents.

As an example for public certs:

SOCIAL_AUTH_SAML_SP_PUBLIC_CERT = '''

-----BEGIN CERTIFICATE——
... cert text ...
-----END CERTIFICATE——

As an example for private keys:

SOCIAL_AUTH_SAML_SP_PRIVATE_KEY = '''
-----BEGIN PRIVATE KEY--
... key text ...
-----END PRIVATE KEY——
'''

4. Configure the remaining settings with information about your application and contact information.
5. Configure the entity ID, SSO URL and certificate for each identity provider (IdP) in use. Multiple SAML IdPs are supported.

Some IdPs may provide user data using attribute names that differ from the default OIDs (https://github.com/omab/python-social-auth/blob/master/social/backends/saml.py). Attribute names may be overridden for each IdP as shown below.

SOCIAL_AUTH_SAML_ENABLED_IDPS = {
    'myidp': {
        'entity_id': 'https://idp.example.com',
        'url': 'https://myidp.example.com/sso',
        'x509cert': '',
    },
    'onelogin': {
        'entity_id': 'https://app.onelogin.com/saml/metadata/123456',
        'url': 'https://example.onelogin.com/trust/saml2/http-post/sso/123456',
        'x509cert': '',
        'attr_user_permanent_id': 'name_id',
        'attr_first_name': 'User.FirstName',
        'attr_last_name': 'User.LastName',
        'attr_username': 'User.email',
        'attr_email': 'User.email',
    },
}

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

6. Click Save when done.

12.5. RADIUS Authentication Settings¶

Ansible Tower can be configured to centrally use RADIUS as a source for authentication information.

1. Access the Configure Tower feature in the Ansible Tower User Interface. For instructions, refer to the Tower Configuration section.
2. Enter in the appropriate RADIUS server settings (skipped when Radius Server field is blank).
3. Click Save when done.

12.6. Using LDAP with Tower¶

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:

1. First, create a user in LDAP that has access to read the entire LDAP structure.

To test if you can make successful queries to the LDAP server, use the following command, 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.

2. Access the Configure Tower feature in the Ansible Tower User Interface. For instructions, refer to the Tower Configuration section.
3. 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.
4. Enter the password to use for the Binding user in the LDAP BIND PASSWORD text field. In this example, the password is ‘passme’.
5. The LDAP USER SEARCH field defines where to search for users while authenticating. In this example, use:

AUTH_LDAP_USER_SEARCH = LDAPSearch(
    'DC=WEBSITE,DC=COM',          # Base DN
    ldap.SCOPE_SUBTREE,           # SCOPE_BASE, SCOPE_ONELEVEL, SCOPE_SUBTREE
    '(sAMAccountName=%(user)s)',  # Query
)

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. For example, to query the AD LDAP using ldapsearch with a filter for the user, use something like:

ldapsearch -x  -H ldap://win -D "CN=josie,CN=Users,DC=website,DC=com" -b "dc=website,dc=com" -w Josie4Cloud objectClass=user

6. If that name is stored in key sAMAccountName, the LDAP USER DN TEMPLATE populates with '(sAMAccountName=%(user)s)'. Similarly, for OpenLDAP, the key is uid–hence the line becomes '(uid=%(user)s)',.
7. In the LDAP GROUP SEARCH text field, specify which groups should be searched and how to search them. In this example, use:

AUTH_LDAP_GROUP_SEARCH = LDAPSearch(
    'DC=website,DC=com',    # Base DN
    ldap.SCOPE_SUBTREE,     # SCOPE_BASE, SCOPE_ONELEVEL, SCOPE_SUBTREE
    '(objectClass=group)',  # Query
)

• 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.

You could make another ldapsearch and check in one group, which is the objectclass to which it belongs. For example:

# admin, grp, website.com
dn: CN=admin,OU=grp,DC=website,DC=com
objectClass: top
objectClass: group
cn: admin
member: CN=both,CN=Users,DC=website,DC=com
distinguishedName: CN=admin,OU=grp,DC=website,DC=com

8. Click to select a group type from the LDAP GROUP TYPE drop-down menu list.
9. Specify the group distinguish name in the LDAP REQUIRE GROUP in order to allow users within that group to access Tower.
10. Specify the group distinguish name in the LDAP DENY GROUP in order to prevent users within that group to access Tower.
11. To enable TLS when the LDAP connection is not using SSL, click the LDAP START TLS toggle to ON. By default, TLS is disabled, with the toggle set to OFF.
12. Specify the user attributes in the LDAP USER ATTRIBUTES MAP text field. In this example, use:

AUTH_LDAP_USER_ATTR_MAP = {
    'first_name': 'givenName',
    'last_name': 'sn',
    'email': 'mail',
}

The above example retrieves users by last name from the key sn in the ldapsearch. You can use the same LDAP query for the user to figure out what keys they are stored under.

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

13. Click Save when done.

With these values entered on this form, you can now make a successful authentication with LDAP.

AUTH_LDAP_GLOBAL_OPTIONS = {
    ldap.OPT_X_TLS_REQUIRE_CERT: False,
}

LOGGING['handlers']['syslog'] = {
    'level': 'DEBUG',
    'filters': ['require_debug_false'],
    'class': 'logging.handlers.SysLogHandler',
    'address': '/dev/log',
    'facility': 'local0',
    'formatter': 'simple',
}

LOGGING['loggers']['django_auth_ldap']['handlers'] = ['syslog']
LOGGING['loggers']['django_auth_ldap']['level'] = 'DEBUG'

AUTH_LDAP_GLOBAL_OPTIONS = {
    ldap.OPT_REFERRALS: False,
}

LOGGING['handlers']['tower_warnings']['level'] =  'DEBUG'

12.7. Organization and Team Mapping¶

Next, you will need to control which users are placed into which Tower organizations based on their username and email address (mapping out your organization admins/users from social or enterprise-level authentication accounts).

Dictionary keys are organization names. Organizations will be created, if not already present and if the license allows for multiple organizations. Otherwise, the single default organization is used regardless of the key.

Values are dictionaries defining the options for each organization’s membership. For each organization, it is possible to specify which users are automatically users of the organization and also which users can administer the organization.

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

• If None, organization admins will not be updated.
• If True, all users using account authentication will automatically be added as admins of the organization.
• If False, no account authentication users will be automatically added as admins of the organization.
• If a string or list of strings, specifies the usernames and emails for users who will be added to the organization. Compiled regular expressions may also be used instead of string literals.

remove_admins: True/False. Defaults to True.

• When True, a user who does not match is removed from the organization’s administrative list.

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

• When True, a user who does not match is removed from the organization’s administrative list.

remove_users: True/False. Defaults to True.

• When True, a user who does not match is removed from the organization’s administrative list.

SOCIAL_AUTH_ORGANIZATION_MAP = {
 Add all users to the default organization.
'Default': {
    'users': True,
},
'Test Org': {
    'admins': ['[email protected]'],
    'users': True,
},
'Test Org 2': {
    'admins': ['[email protected]', re.compile(r'^tower-[^@]+*?@.*$],
    'users': re.compile(r'^[^@].*?@example\.com$'),
},
}

Organization mappings may be specified separately for each account authentication backend. If defined, these configurations will take precedence over the global configuration above.

SOCIAL_AUTH_GOOGLE_OAUTH2_ORGANIZATION_MAP = {}
SOCIAL_AUTH_GITHUB_ORGANIZATION_MAP = {}
SOCIAL_AUTH_GITHUB_ORG_ORGANIZATION_MAP = {}
SOCIAL_AUTH_GITHUB_TEAM_ORGANIZATION_MAP = {}
SOCIAL_AUTH_SAML_ORGANIZATION_MAP = {}

Mapping of team members (users) from social auth accounts. 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. If the license does not allow for multiple organizations, the team will always be assigned to the single default organization.

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

• If None, team members will not be updated.
• If True/False, all social auth users will be added/removed as team members.
• If a string or list of strings, specifies expressions used to match users. User will be added as a team member if the username or email matches. Compiled regular expressions may also be used instead of string literals.

remove: True/False. Defaults to True. When True, a user who does not match the rules above is removed from the team.

SOCIAL_AUTH_TEAM_MAP = {
'My Team': {
    'organization': 'Test Org',
    'users': ['re.compile(r'^[^@]+?@test\.example\.com$')'],
    'remove': True,
},
'Other Team': {
    'organization': 'Test Org 2',
    'users': re.compile(r'^[^@]+?@test2\.example\.com$'),
    'remove': False,
},
}

Team mappings may be specified separately for each account authentication backend, based on which of these you setup. When defined, these configurations take precedence over the the global configuration above.

SOCIAL_AUTH_GOOGLE_OAUTH2_TEAM_MAP = {}
SOCIAL_AUTH_GITHUB_TEAM_MAP = {}
SOCIAL_AUTH_GITHUB_ORG_TEAM_MAP = {}
SOCIAL_AUTH_GITHUB_TEAM_TEAM_MAP = {}
SOCIAL_AUTH_SAML_TEAM_MAP = {}

Uncomment the line below (i.e. set SOCIAL_AUTH_USER_FIELDS to an empty list) to prevent new user accounts from being created. Only users who have previously logged in to Tower using social or enterprise-level authentication or have a user account with a matching email address will be able to login.

SOCIAL_AUTH_USER_FIELDS = []