How authentik signs AWX users in over SAML
A platform team running AWX or Red Hat Ansible Automation Platform can move sign-in to authentik over SAML, and the authentik integrations catalog includes a guide for exactly this setup. The guide covers enterprise authentication settings in AWX, mapping organization and team membership from SAML attributes, and granting superuser rights through a flag. In this model, authentik is the SAML identity provider and AWX is the service provider. authentik issues signed assertions that describe the user, and AWX trusts those assertions to create or update the local account and apply the mappings. Local AWX accounts stay in place, which matters for recovery if the identity provider is unavailable.
Before you start, confirm the field names against the AWX or Ansible Automation Platform version your team runs. The settings page labels, the attribute keys AWX expects and the mapping syntax have changed across releases, so copying names from an older guide can produce a configuration that saves without error but assigns no roles. Ask your team to record the exact AWX version, the AAP release if applicable, and the authentik provider settings (entity ID, ACS URL, signing certificate and NameID format) in one place. Those values are what you will compare against when a login fails.
Decide early which authentik groups or attributes will drive organization and team membership, and who is allowed to set the superuser flag. Superuser mapping is the highest-risk setting in this integration, so restrict the authentik group that can grant it, and keep at least one local administrator account in AWX for recovery. Test with a non-administrator user first, then with a user who should be a superuser, and confirm in AWX that each login produces the expected organization and team memberships before you enable the setup for the wider team.
What you need before configuring SAML for AWX
Before you touch either side of the SAML configuration, the authentik deployment, the AWX or Ansible Automation Platform instance, the network path between them and the certificates they trust all need to be in place. The group naming scheme you agree in authentik determines how cleanly organization and team mapping works later, so settle it first.
Confirm the AWX or AAP version
Check the AWX or Ansible Automation Platform version you run against the authentik AWX integration guide before you start, because the SAML settings screens and the attribute handling you configure can differ between releases. Record the exact version in your change ticket so the steps you follow match the version you operate. If the guide and your version disagree, confirm the difference with the vendor before you change production settings.
A running authentik server and worker
A working authentik deployment has a server container, which runs core with an embedded outpost, a worker container for background tasks, and PostgreSQL, which stores all configuration and data except uploaded files. Docker Compose suits test setups and small-scale production, while the Helm chart's bundled PostgreSQL is intended for demonstration and test environments only. For production, plan a separately managed PostgreSQL database before you create the SAML provider.
Administrator access on both sides
You need an authentik administrator account that can create providers, applications, property mappings and groups, and an AWX or AAP account with system administrator rights to change authentication settings. Confirm who holds each role and keep a second administrator on each side so a misconfigured login does not lock everyone out. Keep a local AWX admin account that does not depend on SAML for recovery.
Network paths and DNS
AWX must reach the authentik endpoints it uses for SAML metadata and assertion consumption, and users' browsers must reach both services on their public names. Confirm DNS records for the authentik and AWX hostnames, the firewall rules between them, and any reverse proxy in front of each service. Any name you use in the SAML entity ID or assertion consumer URL must match exactly what users type in the browser.
TLS certificates both systems trust
The SAML exchange depends on HTTPS endpoints that both systems trust. Confirm that the certificate on each hostname chains to a CA that AWX and authentik's network path accept, and that any internal CA is installed where the AWX control plane needs it. Plan the signing certificate authentik uses for SAML assertions and decide how you will rotate it before it expires.
An agreed group naming scheme
Organization and team mapping depends on attributes that authentik sends in the SAML assertion, so the group names must be settled before you write the mapping rules. Decide which authentik groups correspond to AWX organizations, which correspond to teams, and which, if any, grant superuser rights. Use a consistent prefix so an administrator can tell at a glance which groups feed AWX and which serve other systems. Ask the security team to approve who may hold the superuser group.
Configuring the authentik SAML provider and AWX settings in order
This sequence builds the SAML trust between authentik and AWX, maps user attributes to organizations and teams, and gates superuser access behind a tested non-admin login.
Confirm the AWX URL and attribute plan
Before touching either system, record the exact public URL of your AWX or Ansible Automation Platform controller, the hostname authentik will use, and the group names that will map to organizations and teams. Decide which authentik group or attribute will carry each mapping, and which group, if any, will receive superuser rights. Confirm the SAML entity ID and ACS URL values against the current AWX documentation and the authentik AWX guide, since these must match character for character. The step is done when you have a written attribute and group table that a second administrator has reviewed.
Create the SAML provider and application in authentik
In authentik, create a SAML provider and an application linked to it. Enter the entity ID and the ACS URL that AWX expects, select the signing certificate, and set the NameID and attribute mappings you planned in the previous step so that user name, email, groups and any organization or team attributes appear in the assertion. Bind the application to a policy or group that limits who may sign in. The step is done when the provider and application save without errors and the application appears in the authentik user library for a test account.
Export the metadata and signing certificate
From the authentik SAML provider, download the metadata document and copy the signing certificate. Store both in your configuration repository or secrets store, not in a shared document. Verify that the metadata contains the expected entity ID, the single sign-on endpoint and the certificate, and that the certificate has not expired. The step is done when you can open the metadata file and confirm each of these values matches the provider you just created.
Enter the enterprise authentication settings in AWX
In AWX or Ansible Automation Platform, open the enterprise authentication settings for SAML. Enter the authentik identity provider details from the metadata, the service provider entity ID and the certificate, and set the callback and logout values to the URLs your AWX instance advertises. Leave superuser mapping disabled for now. Save the settings. The step is done when the settings save and the SAML login option appears on the AWX sign-in page.
Set the attribute names for user, organization and team
In the AWX SAML settings, set the attribute names that carry the username, email, organization membership and team membership. These names must match the attribute names in the authentik assertion exactly, including case. Map organization and team attributes to the values you defined in the first step. Open a SAML response from a test sign-in, or use the authentik preview of the assertion, to confirm that each attribute is present and carries the expected values. The step is done when the attribute names in the assertion match the names in AWX.
Test sign-in with a non-admin account
Sign in to AWX through SAML with a test account that belongs to the intended organization and team but has no superuser group membership. Confirm that the account is created or updated, that it lands in the expected organization and team, and that it cannot access administrative settings. Check the AWX log for any SAML errors during the sign-in. The step is done when the test account signs in successfully and the organization and team memberships match the attributes in the assertion.
Enable superuser mapping after a passed test
Only after the non-admin test passes, enable the superuser mapping in AWX and point it at the authentik group you designated for administrators. Keep at least one local administrator account available for recovery, and confirm that it still works. Sign in with a test account in the superuser group and verify administrative access, then sign in with a non-superuser account to confirm it does not gain rights. The step is done when both checks produce the expected access and the recovery account is confirmed.
Choosing how organizations, teams and superusers are assigned
Attribute-driven mapping reads organization and team membership from attributes sent in the SAML assertion, so AWX decides access from the values your identity source already holds. This suits organizations where a user's department, cost center or automation domain is maintained in one place and changes there should flow into AWX without a second edit.
- Single source of truth: Team membership follows the attribute the identity source maintains, so an HR or directory change propagates on the next sign-in.
- Audit clarity: Each grant traces to a named attribute value, which makes the mapping easier to explain to an auditor than manual edits in the AWX interface.
- Change effort: Renaming a team or splitting an organization means updating the attribute values and the mapping rules together, so plan that work before the rename.
- Attribute hygiene risk: If users can edit the attribute, or it is populated from an unreviewed source, AWX will trust it. Confirm who controls each attribute.
- Mapping limits: Confirm in the AWX and authentik documentation how multi-valued attributes and removals are handled in your release.
Before you rely on this approach, export a sample assertion from a test user and confirm the exact attribute names and values AWX receives.
Group-based rules map directory or authentik groups to AWX organizations, teams and roles. Platform teams usually find this the most familiar model, because access reviews already happen on groups in the identity provider and AWX simply follows them.
- Familiar review path: Access reviews performed on groups in the identity provider cover AWX without a separate AWX review step.
- Audit clarity: Group membership is visible in one place, but a group name alone does not show what AWX permissions it grants, so document each mapping rule.
- Change effort: Adding a team usually means a new group and a new rule. Restructuring groups can silently change AWX access, so test membership changes in staging first.
- Superuser risk: A broad group, such as one covering all engineers, mapped to the superuser flag gives every member platform-wide control. Keep superuser mapping to a dedicated, small group.
- Nested or inherited groups: Confirm whether group membership is evaluated directly or through nesting in your environment before relying on it.
Review the full list of groups that can reach AWX administrative roles at least as often as you review the groups themselves.
Manual assignment means an administrator adds users to AWX organizations, teams and roles directly in the AWX interface after they sign in through SAML. It is suited to a pilot with a small, known group of users, where the cost of building attribute or group rules is not yet justified.
- Fast start: No mapping rules need to be designed before the first users sign in, which keeps the pilot focused on login and access testing.
- Audit clarity: Changes are made by named AWX administrators, but they live in AWX rather than the identity provider, so record each change in a change log.
- Change effort: Every role change is a manual edit, and manual edits drift from the identity source over time. Plan the migration to automated mapping before the pilot ends.
- Superuser control: Limit superuser rights to a short, named list during the pilot and remove them when the pilot closes.
- Recovery path: Keep a local administrator account for recovery, and confirm it still works after SAML is enabled.
Before expanding beyond the pilot, confirm which assignments will move to automated rules and who approves them.
Attributes and roles mapped from authentik to AWX
This table lists each identity value authentik sends to AWX during SAML sign-in, the AWX setting that consumes it, and the rule to apply when the value is empty or unexpected. Read each row as a contract between the two systems: confirm the attribute name on the authentik side and the matching field name in the current AWX documentation before you enable mapping in production.
| Identity value | authentik source | AWX setting and rule for empty or unexpected values |
|---|---|---|
| Username | The authentik user's username, mapped through the SAML NameID or a username attribute in the property mappings | Used as the AWX login name. Confirm which NameID format the AWX SAML settings expect. If the value is empty, the login should fail rather than create an unnamed account. |
| Email address | The user's email attribute, exported through a SAML property mapping | Populates the AWX user email field. Confirm the attribute name AWX reads. If empty, allow sign-in but flag the account for review, since notification and audit fields depend on it. |
| Organization membership | A group or attribute listing the organizations the user belongs to, exported as a multi-value SAML attribute | Confirm the AWX organization mapping keys and whether they match organization names or IDs. Unmatched values should be ignored, not auto-created, unless you have approved that behavior. |
| Team membership | Groups from the authentik user's group list, exported as a multi-value attribute with a stable naming scheme | Confirm the AWX team mapping rule and the attribute name it reads. Use a dedicated naming prefix so unrelated authentik groups do not create AWX teams by accident. |
| Superuser status | A specific authentik group (for example, an AWX administrators group) or a boolean attribute carried in the assertion | Grant only through an explicit group or attribute. Confirm the AWX superuser flag key. If the value is missing or unexpected, the user should sign in as a standard user, never as a superuser by default. |
| Break-glass local admin | No SAML attribute; this account lives in AWX itself | Keep a local superuser in AWX that does not depend on SAML. Confirm that local login remains enabled after SAML is configured so administrators can recover from an identity outage. |
| Attribute name changes | Property mapping names in authentik | Confirm names against the AWX release you run. A renamed attribute silently drops team or superuser grants, so test each role with a non-admin and an admin account after every change. |
Hardening SAML sign-in to AWX
Signing in to AWX through authentik makes the identity provider a control point for every administrator. The cards below cover the controls that keep that path safe: certificate handling, a recovery account, superuser scoping, MFA, and event logging. Each one should be verified in your own environment before AWX goes into production use.
Plan SAML signing certificate rotation
The SAML trust between authentik and AWX depends on the signing certificate and the metadata exchanged when the provider is configured. Record which certificate and key pair each side uses, who holds the private key, and the date it expires. Before rotation, confirm with the AWX documentation for your version whether it reloads IdP metadata on its own or needs a manual update, and test the new certificate in a non-production AWX first. Rotation is a planned change, not an incident response step.
Keep a local break-glass administrator
If authentik is down, misconfigured, or its certificate has expired, nobody can sign in through SAML. Keep at least one local AWX administrator with a strong, separately stored password and confirm it still works after the SAML cutover. Limit its use to recovery, log each use, and review the account on a fixed schedule. Confirm with your AWX version's documentation how local login is enabled or restricted when enterprise authentication is active.
Scope superuser rights to a group
Superuser status in AWX should follow membership in a named authentik group, not individual grants made by hand. Map the superuser flag from a group claim in the SAML assertion, and keep that group small and owned by the platform team. Check the attribute mapping on a test account with and without the group, because an overly broad group match is the most common way a standard user ends up with full control of automation.
Enforce MFA for the admin group
AWX administrators can run playbooks against production inventories, so their sign-in should require a second factor. Configure an authentik authentication flow or policy bound to the admin group so that members must complete MFA before the SAML assertion is issued. Confirm which second factors your authentik version supports for that flow, and test the enrollment path for a new administrator before they need it.
Log authentication and role changes
Record who signed in to AWX, from where, and which groups and flags were in the assertion at that time. Forward authentik event logs and AWX logs to a central store you control, and alert on failed admin sign-ins and on any change to superuser or organization mapping. Enhanced audit logging is listed as an authentik Enterprise feature on the pricing page, so confirm with authentik whether the open-source event log meets your retention and detail needs before you rely on it.
Common SAML failures with AWX and how to fix them
This table lists the failures teams most often hit when wiring authentik SAML into AWX or Ansible Automation Platform, with the likely cause and the fix for each. Read it by matching the symptom you see at login to a row, then checking the configuration named in the cause before changing anything else.
| Symptom | Likely cause | Fix |
|---|---|---|
| SAML error about an unknown or mismatched entity ID | The SP entity ID in the authentik provider does not match the entity ID AWX sends, often because the AWX base URL differs between the two sides | Copy the AWX base URL exactly into both the authentik provider and the AWX SAML settings, including scheme and any port, then retry sign-in |
| Assertion rejected at the assertion consumer service (ACS) | The ACS URL in authentik was built from a different hostname than the one users browse to, such as an internal name or an old DNS record | Set the ACS URL to the public AWX address users actually use, and confirm the authentik application targets that same host |
| Signature or certificate validation fails | The signing certificate in AWX does not match the certificate authentik uses to sign assertions, usually after the certificate was rotated or pasted from the wrong provider | Re-export the signing certificate from the authentik SAML provider and replace the value in AWX, then confirm the signing settings match on both sides |
| Assertion appears expired or not yet valid | Clock drift between the authentik server, the AWX host and the user's browser, so the NotBefore or NotOnOrAfter window fails | Synchronize time on all three with NTP and check the authentik and AWX hosts are in the same time zone reference, then retry |
| User signs in but has no teams | The team mapping in AWX expects an attribute name that authentik does not send, or the attribute value differs in case or format from what the mapping rule matches | Compare the attribute names in a test assertion with the names in the AWX team mapping, then correct the property mapping in authentik or the mapping rule in AWX |
| User signs in and receives no organization | The organization mapping rule does not match the attribute value or group name sent by authentik, so AWX creates no membership | Check the organization rule against the exact group or attribute value in the assertion, and confirm the user is a member of the group in authentik |
| Superuser flag is not applied | The superuser mapping references a group or attribute that is missing from the assertion, or the user was created before the mapping changed and keeps old flags | Confirm the superuser mapping in AWX matches the authentik group sent in the assertion, then sign the user out and in again to refresh their permissions |
| Login loop back to the sign-in page behind a reverse proxy | The proxy strips or rewrites headers that AWX uses to build its URLs, or terminates TLS so AWX sees http and rejects the secure cookie or redirect | Pass the forwarded protocol and host headers through the proxy, set the AWX public URL to https, and confirm the SAML callback path is not blocked |
Questions teams ask before configuring AWX SAML with authentik
Can our team configure AWX SAML with authentik without outside help?
Yes, a team with administrator access to both AWX or Red Hat Ansible Automation Platform and authentik can usually do this in-house, provided someone owns the SAML settings and the group design. The authentik AWX guide in the integrations catalog covers the enterprise authentication setup. The harder part is rarely the initial connection. It is deciding how groups in authentik become organizations, teams and superuser rights in AWX, then proving that a user lands in the right place. Teams without recent SAML experience, or those who must keep a working local admin during the change, should plan extra test time.
What makes the AWX SAML effort larger or smaller?
Four factors drive most of the effort:
- The AWX or Ansible Automation Platform version, since the settings screens and attribute handling must match your release.
- The number of organizations and teams that need mapping from authentik attributes.
- How attributes and groups are designed in authentik, including whether group names are stable and whether superuser access is granted from a dedicated group.
- Existing local accounts, which need a decision on whether they stay, merge or are retired.
A small single-organization instance with clean groups is far simpler than a multi-organization platform with years of local users.
How long does planning and testing take in our environment?
No fixed duration applies because it depends on your version, identity design and change window. Planning covers reading your current AWX authentication settings, agreeing the attribute and group model, and listing test users for each role. Testing should cover a normal user, an organization member, a team member and a superuser, plus a sign-in after a session expires. Ask any partner or internal team for a written plan with named test cases before work starts, and check it against a non-production AWX instance first.
What do we need to provide for the AWX SAML work?
You need administrator access to authentik to create the SAML provider and application, and administrator access to AWX or Ansible Automation Platform to change authentication settings. Expect to provide a sign-off on the group design, a named owner for who may become a superuser, and at least a few test accounts covering different roles. A staging AWX instance and a documented break-glass local admin are also useful. Confirm these items in writing so the scope and responsibilities are clear before any change is made.
Which SAML settings and mappings should we confirm before go-live?
Confirm the entity IDs, assertion consumer URL and certificate handling against the current authentik guide, and confirm which authentik attributes or groups feed AWX organization, team and superuser mapping. Check how users are created on first login and whether mapping updates existing memberships. Verify that the superuser rule is restricted to a small, named group. Record each setting in a change ticket so an auditor or colleague can trace who granted access and why.
Is an outside partner worth it for AWX SAML with authentik?
A partner is worth considering when the instance is shared by many teams, when organization and team mapping must follow an existing role model, or when staff time is limited. DeployOpen plans, implements and documents open-source platforms in infrastructure you control, and most engagements are fixed-scope with scope, deliverables and timelines agreed in writing before work starts. Ask for a written scope that names the AWX version, the mapping rules, the test cases and the handover items. Quotes follow from that scope, and ongoing support is available as a separate retainer.
What are the recurring costs after the integration is live?
The integration itself adds little recurring cost, but ongoing work includes applying AWX and authentik updates, reviewing group membership, and retesting SAML after version changes. Authentik's Open Source edition is free, and its pricing page lists Enterprise pricing per user for enterprise features. Confirm with the vendor which edition and features your environment needs, and check whether your AWX or Ansible Automation Platform subscription already covers the work. Ask any partner to separate one-time setup from recurring support in the quote.
Keeping an administrator path when SAML fails
Test a local administrator path before you switch AWX or Ansible Automation Platform to SAML sign-in. Once SAML is the only enabled login method, a wrong attribute mapping, an expired signing certificate or a mistaken change to the authentik provider can lock every operator out of the controller at once. Keep a local superuser that authenticates against the platform's own database, confirm that it can sign in with the SAML login path disabled or unavailable to it, and record the exact steps to re-enable SAML if you need to roll back. Confirm the current procedure for the local account and the login settings in the AWX or Ansible Automation Platform documentation for your version, since the mechanics differ between the open-source project and the subscription product.
Verify the fallback in a staging instance or a maintenance window, not during an incident. Sign in with the local account, check that it has the superuser rights you expect, run a job that uses a credential you can see, and log out. Then sign in as a SAML user from each mapped organization and team, and confirm that a user without the superuser flag cannot reach the settings that the local account controls. Write down the result, the date and the version tested. Repeat the check after every change to authentik groups, attribute mappings or the SAML certificate, because those are the changes most likely to break the path you depend on.
Decide who holds the credentials before cutover, not after. Name at least two people from the platform team who can retrieve the local password from your secrets store, and make the access request auditable. Store the recovery procedure next to the credential's access rules, not on the AWX host itself, so a controller outage does not also hide the steps. Limit use of the account to recovery events, record each use and rotate the password after every use or on a schedule your security team sets. Ask your security or identity lead to approve this model in writing, because it sets the boundary between SSO administration and emergency access for the whole platform.
