21. Setting up Enterprise Authentication¶

21.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://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app. 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 Authentication from the Settings () Menu screen.

2. Select the Azure AD tab if it is not already the default view.

3. The Azure AD OAuth2 Callback URL field is already pre-populated and non-editable.

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.

Following Azure AD’s documentation for connecting your app to Microsoft Azure Active Directory, supply the key (shown at one time only) to the client for authentication.

5. Copy and paste the actual secret key created for your Azure AD application 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 the Azure AD Identity Platform (v2) overview.

21.2. LDAP Authentication¶

Refer to the Setting up LDAP Authentication section.

21.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 Authentication from the Settings () Menu screen.

The Azure AD tab displays initially by default.

2. Select the Radius tab.

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.

21.4. 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). Ansible Tower can be configured to talk with SAML in order to authenticate (create/login/logout) Tower users. User Team and Organization membership can be embedded in the SAML response to Tower.

The following instructions describe Ansible Tower as the service provider. To authenticate users through RHSSO (keycloak), refer to the Red Hat Single Sign On Integration with Ansible Tower blog.

To setup SAML authentication:

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

The Azure AD tab displays initially by default.

2. Select the SAML tab.

The following steps describe all the fields and what they are used for. To get transparent SAML logins functional, the minimum required fields are marked with an asterisk (*) in the user interface.

3. The SAML Assertion Consume Service (ACS) URL and SAML Service Provider Metadata URL fields are pre-populated and are non-editable. Contact the Identity Provider administrator and provide the information contained in these fields.

4. 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 Settings icon. Through the API, it can be viewed in the /api/v2/settings/system, under the TOWER_URL_BASE 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. Ensure that the Base URL matches the FQDN of the load balancer (if used).

Note

The Tower Base URL is different for each node in a cluster. Commonly, a load balancer will sit in front of many tower cluster nodes to provide a single entry point, Tower Cluster FQDN. The SAML Service Provider must be able establish an outbound connection and route to the Tower Cluster Node or Tower Cluster FQDN set in the SAML Service Provider Entity ID.

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

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

Note

The SAML Service Provider Public Certificate field should contain the entire certificate, including the “—–BEGIN CERTIFICATE—–” and “—–END CERTIFICATE—–“.

If you are using a CA bundle with your certificate, include the entire bundle in this field.

As an example for public certs:

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

6. 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——

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

Note

These fields are required in order to properly configure SAML within Tower.

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

Warning

attr_username must reference a unique per-account attribute. For example, if attr_username references User.email and a SAML user that shares the same email with another user (including a non-SAML user), the duplicated email accounts will be merged. Be aware that this same behavior exists for System Admin users, thus a SAML login with the same email address as the System Admin user will login with System Admin privileges. For future reference, you can remove (or add) Admin Privileges based on SAML mappings, as described in subsequent steps.

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. Optionally provide the SAML Organization Map. For further detail, see Organization and Team Mapping.

12. Tower can be configured to look for particular attributes that contain Team and Organization membership to associate with users when they log into Tower. The attribute names are defined in the SAML Organization Attribute Mapping and the SAML Team Attribute Mapping fields.

Example SAML Organization Attribute Mapping

Below is an example SAML attribute that embeds user organization membership in the attribute member-of.

<saml2:AttributeStatement>
    <saml2:Attribute FriendlyName="member-of" Name="member-of"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml2:AttributeValue>Engineering</saml2:AttributeValue>
        <saml2:AttributeValue>IT</saml2:AttributeValue>
        <saml2:AttributeValue>HR</saml2:AttributeValue>
        <saml2:AttributeValue>Sales</saml2:AttributeValue>
    </saml2:Attribute>
    <saml2:Attribute FriendlyName="admin-of" Name="admin-of"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
        <saml2:AttributeValue>Engineering</saml2:AttributeValue>
    </saml2:Attribute>
</saml2:AttributeStatement>

Below is the corresponding Tower configuration.

{
  "saml_attr": "member-of",
  "saml_admin_attr": "admin-of",
  "remove": true,
  "remove_admins": false
}

saml_attr: is the SAML attribute name where the organization array can be found and remove is set to True to remove a user from all organizations before adding the user to the list of Organizations. To keep the user in whatever Organization(s) they are in while adding the user to the Organization(s) in the SAML attribute, set remove to False.

saml_admin_attr: Similar to the saml_attr attribute, but instead of conveying organization membership, this attribute conveys admin organization permissions.

Example SAML Team Attribute Mapping

Below is another example of a SAML attribute that contains a Team membership in a list.

<saml:AttributeStatement>
     <saml:Attribute
        xmlns:x500="urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"
        x500:Encoding="LDAP"
        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"
        Name="urn:oid:1.3.6.1.4.1.5923.1.1.1.1"
        FriendlyName="eduPersonAffiliation">
        <saml:AttributeValue
            xsi:type="xs:string">member</saml:AttributeValue>
        <saml:AttributeValue
            xsi:type="xs:string">staff</saml:AttributeValue>
        </saml:Attribute>
</saml:AttributeStatement>

{
    "saml_attr": "eduPersonAffiliation",
    "remove": true,
    "team_org_map": [
    {
        "team": "member",
        "organization": "Default1"
    },
    {
        "team": "staff",
        "organization": "Default2"
    }
  ]
}

• saml_attr: The SAML attribute name where the team array can be found.

• remove: Set remove to True to remove user from all Teams before adding the user to the list of Teams. To keep the user in whatever Team(s) they are in while adding the user to the Team(s) in the SAML attribute, set remove to False.

• team_org_map: An array of dictionaries of the form { "team": "<AWX Team Name>", "organization": "<AWX Org Name>" } that defines mapping from Tower Team -> Tower Organization. This is needed because the same named Team can exist in multiple Organizations in Tower. The organization to which a team listed in a SAML attribute belongs to, would be ambiguous without this mapping.

You could create an alias to override both Teams and Orgs in the SAML Team Attribute Mapping. This option becomes very handy in cases when the SAML backend sends out complex group names, like in the example below:

{
 "remove": false,
 "team_org_map": [
  {
   "team": "internal:unix:domain:admins",
   "organization": "Default",
   "team_alias": "Administrators"
  },
  {
   "team": "Domain Users",
   "organization_alias": "OrgAlias",
   "organization": "Default"
  }
 ],
 "saml_attr": "member-of"
}

Once the user authenticates, Tower creates organization and team aliases, as expected.

13. Optionally provide team membership mapping in the SAML Team Map field. For further detail, see Organization and Team Mapping.

14. Optionally provide security settings in the SAML Security Config field. This field is the equivalent to the SOCIAL_AUTH_SAML_SECURITY_CONFIG field in the API. Refer to the OneLogin’s SAML Python Toolkit for further detail.

Tower uses the python-social-auth library when users log in through SAML. This library relies on the python-saml library to make available the settings for the next two optional fields, SAML Service Provider Extra Configuration Data and SAML IDP to EXTRA_DATA Attribute Mapping.

15. The SAML Service Provider Extra Configuration Data field is equivalent to the SOCIAL_AUTH_SAML_SP_EXTRA in the API. Refer to the python-saml library documentation to learn about the valid service provider extra (SP_EXTRA) parameters.

16. The SAML IDP to EXTRA_DATA Attribute Mapping field is equivalent to the SOCIAL_AUTH_SAML_EXTRA_DATA in the API. See Python’s SAML Advanced Settings documentation for more information.

17. Click Save when done.

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

    

21.4.1. Transparent SAML Logins¶

For transparent logins to work, you must first get IdP-initiated logins to work. To achieve this:

1. Set the RelayState on the IdP to the key of the IdP definition in the SAML Enabled Identity Providers field as previously described. In the example given above, RelayState would need to be either myidp or onelogin.

2. Once this is working, in the Systems window of the Settings () menu of the Ansible Tower User Interface, use the Login Redirect Override URL field to specify the redirect URL for non-logged-in users to somewhere other than the default Tower login page. This should be set to /sso/login/saml/?idp=<name-of-your-idp> for transparent SAML login, as shown in the example.

Note

The above is a sample of a typical IdP format, but may not be the correct format for your particular case. You may need to reach out to your IdP for the correct transparent redirect URL as that URL is not the same for all IdPs.

3. After transparent SAML login is configured, to log in using local credentials or a different SSO, go directly to https://<your-tower-server>/login. This provides the standard Tower login page, including SSO authentication buttons, and allows you to log in with any configured method.

21.5. TACACS+ Authentication Settings¶

Terminal Access Controller Access-Control System Plus (TACACS+) is a protocol that handles remote authentication and related services for networked access control through a centralized server. In particular, TACACS+ provides authentication, authorization and accounting (AAA) services, in which you can configure Ansible Tower to use as a source for authentication.

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

The Azure AD tab displays initially by default.

2. Select the TACACs+ tab.

3. Enter information in the following fields:

• TACACS+ Server: Provide the hostname or IP address of the TACACS+ server with which to authenticate. If this field is left blank, TACACS+ authentication is disabled.

• TACACS+ Port: TACACS+ uses port 49 by default, which is already pre-populated.

• TACACS+ Secret: Secret key for TACACS+ authentication server.

• TACACS+ Auth Session Timeout: Session timeout value in seconds. The default is 5 seconds.

• TACACS+ Authentication Protocol: The protocol used by TACACS+ client. Options are ascii or pap.

4. Click Save when done.