Overview
This article covers the configuration of AWX/AAP to use SAML Authentication via Microsoft Active Directory Federation Services. It includes Controller configuration as well as example ADFS Claim rules. Tested on AAP 2.3 & 2.4
Limitations
As of 2.3/2.4, there are some RBAC-related limitations when using SAML Authentication. The roles that can be mapped via SAML are:
- Org member
- Org admin
- Team member
- Team admin
- Auditor
- Global Admin
More fine granular role mappings (like Job Template Admin, Project Admin, Inventory Admin) are not possible via SAML.
Furthermore, mapped Org Admins need to have a Project associated with their Org before they can create Job Templates.
Example Controller SAML Settings
Note that only Settings that need to be modified from default are covered
| Setting | Value | Comment |
|---|---|---|
| SAML Service Provider Entity ID | e.g. “my-awx” | |
| Automatically Create Organizations and Teams on SAML Login | On | |
| SAML Service Provider Public Certificate | AWX Controller Cert | |
| SAML Service Provider Private Key | AWX Controller Private Key | |
| SAML Service Provider Organization Info | {
“de-CH”: {
“displayname”: “Automation Platform”,
“url”: “https://my-awx.my-domain.com”,
“name”: “My-AWX”
}
} |
|
| SAML Service Provider Technical Contact | {
“givenName”: “AWX-Admins”,
“emailAddress”: “AWX@my-domain.com”
} |
|
| SAML Service Provider Support Contact | same as Technical Contact | |
| SAML Enabled Identity Providers | {
“ADFS”: {
“attr_email”: “an:email”,
“x509cert”: “insert adfs cert here”,
“url”: “https://my-adfs.my-domain.com/adfs/ls/”,
“attr_last_name”: “an:lastname”,
“attr_first_name”: “an:firstname”,
“attr_user_permanent_id”: “name_id”,
“entity_id”: “http://my-adfs.my-domain.com/adfs/services/trust”,
“attr_username”: “an:username”
}
} |
The attr_ parameters will map to the Users and their usernames, first names, last names, email addresses and are specific to what is sent in the assertion |
| SAML Organization Map | {
“My-Org”: {
“users”: true
}
} |
add this if you want all authenticated users to be added to My-Org |
| SAML Organization Attribute Mapping | {
“saml_admin_attr”: “an:orgadmin”,
“remove”: true,
“remove_admins”: true,
“saml_attr”: “an:orgmember”
} |
This means that users with an an:orgmember claim will be added as Members to the Org specified in the claim and users with an an:orgadmin claim will be added as Admins to the Org specified in the claim. See example claim rules below |
| SAML Team Map | not needed due to attribute mapping | |
| SAML Team Attribute Mapping | {
“team_org_map”: [
{
“team_alias”: “Developers”,
“team”: “member_devs”,
“organization”: “Developers”
},
{
“team_alias”: “Operations”,
“team”: “member_ops”,
“organization”: “Operations”
}
],
“remove”: true,
“saml_attr”: “an:teammember”
} |
This section handles members to team-mapping via the an:teammember claim (users will be added as a Member of whatever Team is sent in the an:teammember Attribute ). Additionally, the teams are mapped to the Organizations in the “team_org_map” section. Aliases are optional. |
| SAML User Flags Attribute Mapping | {
“is_superuser_value”: [
“1”
],
“is_superuser_attr”: “an:superuser”
} |
If a “1” is sent as value of the an:superuser claim, the user will get the System Administrator Role |
| SAML Security Config | {
“requestedAuthnContext”: false
} |
|
| SAML Service Provider extra configuration data | null | |
| SAML IDP to extra_data attribute mapping | null |
Example ADFS Claim rules
@RuleTemplate = "LdapClaims"
@RuleName = "UPN as Claim"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"), query = ";userPrincipalName;{0}", param = c.Value);
@RuleTemplate = "MapClaims"
@RuleName = "UPN As NAMEID"
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
@RuleName = "Issue LDAP Attributes"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("an:firstname", "an:lastname", "an:username", "an:email"), query = ";givenName,sn,sAMAccountName,mail;{0}", param = c.Value);
@RuleName = "Add Group Membership"
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> add(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/Group"), query = ";tokenGroups;{0}", param = c.Value);
@RuleName = "AAP - Team Member"
c:[Type == "http://schemas.xmlsoap.org/claims/Group", Value =~ "(?i)RO_AAP_(?!Hub)(\w+)_Member"]
=> issue(Type = "an:teammember", Value = regexreplace(c.Value, "RO_AAP_(?!Hub)(\w+)_Member", "$1"));
@RuleName = "AAP - Org Member"
c:[Type == "http://schemas.xmlsoap.org/claims/Group", Value =~ "(?i)AWX_(?!Hub)(\w+)_Member"]
=> issue(Type = "an:orgmember", Value = regexreplace(c.Value, "AWX_(?!Hub)(\w+)_Member", "$1"));
@RuleName = "AAP - Org Admins"
c:[Type == "http://schemas.xmlsoap.org/claims/Group", Value =~ "(?i)AWX_(?!Hub)(\w+)_Admin"]
=> issue(Type = "an:orgadmin", Value = regexreplace(c.Value, "AWX_(?!Hub)(\w+)_Admin", "$1"));
@RuleName = "AAP - Super User"
c:[Type == "http://schemas.xmlsoap.org/claims/Group", Value =~ "(?i)AWX_Superuser"]
=> issue(Type = "an:superuser", Value = "1");
- Issue the claims an:firstname, an:lastname, an:username, an:email in every assertion
- For users that have a AWX_Team_Member role, issue in the an:teammember claim (exclude "AWX_Hub_* Roles)
- For users that have a AWX_Team_Admin role, issue in the an:orgmember and an:orgadmin claims (exclude "AWX_Hub_* Roles)
- For users that have a AWX_Superuser role, issue a “1” in the an:superuser claim
Hope this helps!