Topics:
Note
For LDAP authentication, see Setting up LDAP Authentication.
SAML, RADIUS, and TACACS+ users are categorized as ‘Enterprise’ users. The following rules apply to Enterprise users:
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.
The Configure Tower window opens, displaying the Authentication tab initially by default.
Once the application is registered, Azure displays the Application ID and Object ID.
Following Azure AD’s documentation, Connect your app to Microsoft Azure Active Directory: Create the Key, supply the key (shown at one time only) to the client for authentication.
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
Note
SAML authentication is a feature specific to Enterprise-level license holders.
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:
The Configure Tower window opens, displaying the Authentication tab initially by default.
/api/v2/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. 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.
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——
As an example for private keys:
-----BEGIN PRIVATE KEY--
... key text ...
-----END PRIVATE KEY——
{
"en-US": {
"url": "http://www.example.com",
"displayname": "Example",
"name": "example"
}
}
For example:
{
"givenName": "Some User",
"emailAddress": "[email protected]"
}
For example:
{
"givenName": "Some User",
"emailAddress": "[email protected]"
}
For example:
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 toname_id
ifSAML: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 theattr_user_permanent_id
toname_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.
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.
{
"SOCIAL_AUTH_SAML_ORGANIZATION_ATTR": {
"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 Map 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.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.
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.SOCIAL_AUTH_SAML_EXTRA_DATA
in the API. See Python’s SAML Advanced Settings documentation for more information.Click Save when done.
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.
Note
RADIUS account authentication is a feature specific to Enterprise-level license holders.
Ansible Tower can be configured to centrally use RADIUS as a source for authentication information.
The Configure Tower window opens, displaying the Authentication tab initially by default.
Note
TACACS+ account authentication is a feature specific to Enterprise-level license holders.
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.
The Authentication tab displays initially by default.