13. Setting up Enterprise Authentication¶

13.1. Azure Active Directory (AD)¶

To set up enterprise authentication for Microsoft Azure Active Directory (AD), you will need to obtain an OAuth2 key and secret by registering your organization-owned application from Azure at https://auth0.com/docs/connections/enterprise/azure-active-directory. Each key and secret must belong to a unique application and cannot be shared or reused between different authentication backends. In order to register the application, you must supply it with your webpage URL, which is the Callback URL shown in the Configure Tower user interface.

1. In the Ansible Tower User Interface, click Configure Tower from the Settings () Menu screen.

The Authentication tab displays initially by default.

2. In the Sub Category field, select Azure AD from the drop-down list.

3. Use the Azure AD OAuth2 Callback URL to supply Azure AD when it prompts for your application’s Sign-on URL.

Once the application is registered, Azure displays the Application ID and Object ID.

4. Copy and paste Azure’s Application ID to the Azure AD OAuth2 Key field of the Configure Tower - Authentication screen.
5. Copy and paste Azure’s Object ID to the Azure AD OAuth2 Secret field of the Configure Tower - Authentication screen.
6. For details on completing the mapping fields, see Organization and Team Mapping.
7. Click Save when done.
8. To verify that the authentication was configured correctly, logout of Ansible Tower and the login screen will now display the Microsoft Azure logo to allow logging in with those credentials.

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

13.2. SAML Authentication Settings¶

SAML allows the exchange of authentication and authorization data between an Identity Provider (IdP - a system of servers that provide the Single Sign On service) and a Service Provider (in this case, Ansible Tower).

To setup SAML authentication:

1. In the Ansible Tower User Interface, click Configure Tower from the Settings () Menu screen.

The Authentication tab displays initially by default.

2. In the Sub Category field, select SAML from the drop-down list.

The SAML Service Provider Callback URL and SAML Service Provider Metadata URL fields are pre-populated and are non-editable.

3. Set the SAML Service Provider Entity ID to be the same as the Tower Base URL. The Tower Base URL can be found in the System tab of the Configure Tower screen, which you can access through the menu. Through the API, it can be viewed in the /api/v1/settings/system, under the TOWER_BASE_URL variable. The Entity ID can be set to any one of the individual Tower Cluster Nodes, but it is good practice to set it to the URL of the Service Provider.

In this example, the Service Provider is the Tower Cluster, and therefore, the ID is set to the Tower Cluster FQDN.

4. Create a server certificate for the Ansible cluster. Typically when an Ansible cluster is configured, the Tower nodes will be configured to handle HTTP traffic only and the load balancer will be an SSL Termination Point. In this case, an SSL certificate is required for the load balancer, and not for the individual Tower Cluster Nodes. SSL can either be enabled or disabled per individual Tower node, but should be disabled when using an SSL terminated load balancer. It is recommended to use a non-expiring self signed certificate to avoid periodically updating certificates. This way, authentication will not fail in case someone forgets to update the certificate.

As an example for public certs:

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

5. Create an optional private key for Tower to use as a service provider (SP) and enter it in the SAML Service Provider Private Key field.

As an example for private keys:

-----BEGIN PRIVATE KEY--
... key text ...
-----END PRIVATE KEY——

6. Contact the Identity Provider administrator and provide the following information:

• SAML Assertion Consumer Services URL. This is the Tower Callback URL auto-generated by Tower and is shown in the SAML Service Provider Callback URL field. Ensure that the Base URL matches the FQDN of the load balancer (if used).
• Service Provider Entity ID. This is the URL entered in the SAML Service Provider Entity ID field.

7. Optionally provide the IdP with some details about the Tower cluster during the SSO process in the SAML Service Provider Organization Info field.

{
"en-US": {
"url": "http://www.example.com",
"displayname": "Example",
"name": "example"
}

For example:

8. Provide the IdP with the technical contact information in the SAML Service Provider Technical Contact field. Do not remove the contents of this field.

{
"givenName": "Some User",
"emailAddress": "[email protected]"
}

For example:

9. Provide the IdP with the support contact information in the SAML Service Provider Support Contact field. Do not remove the contents of this field.

{
"givenName": "Some User",
"emailAddress": "[email protected]"
}

For example:

10. In the SAML Enabled Identity Providers field, provide information on how to connect to each Identity Provider listed. Tower expects the following SAML attributes in the example below:

Username(urn:oid:0.9.2342.19200300.100.1.1)
Email(urn:oid:0.9.2342.19200300.100.1.3)
FirstName(urn:oid:2.5.4.42)
LastName(urn:oid:2.5.4.4)

If these attributes are not known, map existing SAML attributes to lastname, firstname, email and username.

Configure the required keys for each IDp:

• attr_user_permanent_id - the unique identifier for the user. It can be configured to match any of the attribute sent from the IdP. Usually, it is set to name_id if SAML:nameid attribute is sent to the Tower node or it can be the username attribute, or a custom unique identifier.
• entity_id - the Entity ID provided by the Identity Provider administrator. The admin creates a SAML profile for Tower and it generates a unique URL.
• url - the Single Sign On (SSO) URL Tower redirects the user to, when SSO is activated.
• x509_cert - the certificate provided by the IdP admin generated from the SAML profile created on the Identity Provider. Remove the --BEGIN CERTIFICATE-- and --END CERTIFICATE-- headers, then enter the cert as one non-breaking string.

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). The SAML NameID is a special attribute used by some Identity Providers to tell the Service Provider (Tower cluster) what the unique user identifier is. If it is used, set the attr_user_permanent_id to name_id as shown in the example. Other attribute names may be overridden for each IdP as shown below.

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

Note

The IdP provides the email, last name and firstname using the well known SAML urn. The IdP uses a custom SAML attribute to identify a user, which is an attribute that Tower is unable to read. Instead, Tower can understand the unique identifier name, which is the URN. Use the URN listed in the SAML “Name” attribute for the user attributes as shown in the example below.

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

12. Click Save when done.

13. To verify that the authentication was configured correctly, load the auto-generated URL found in the SAML Service Provider Metadata URL into a browser. It should output XML output, otherwise, it is not configured correctly.

    Alternatively, logout of Ansible Tower and the login screen will now display the SAML logo to indicate it as a alternate method of logging into Ansible Tower.

    

13.3. RADIUS Authentication Settings¶

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

1. In the Ansible Tower User Interface, click Configure Tower from the Settings () Menu screen.

The Authentication tab displays initially by default.

2. In the Sub Category field, select Radius from the drop-down list.

3. Enter the Host or IP of the Radius server in the Radius Server field. If this field is left blank, Radius authentication is disabled.
4. Enter the port and secret information in the next two fields.

5. Click Save when done.