Learn Authentik - SAML Service Provider Integrations

#Introduction

In episode 14, you configured your first SAML provider — Authentik can now issue assertions. Episode 15 answers the real question: how do you connect that provider with real Service Providers (SPs)? Because SAML only has meaning when there are two parties, and every SP has a slightly different integration method and attribute requirements.

The key lies in two things: correct metadata exchange, and attribute mapping that matches the SP's expectations. SAML failures almost always stem from one of these two — not the cryptography, but the data not matching.

#Metadata Exchange: Two Directions

A healthy SAML integration starts with metadata, not manual value copying:

1. IdP → SP. Copy the Authentik IdP metadata URL (https://authentik.example.com/application/saml/<slug>/metadata/) or download its XML. Paste it into the application's SAML form. Many SPs allow import by URL or XML file upload.
2. SP → IdP. Conversely, if the SP provides XML metadata, create a new provider with the SAML Provider from Metadata type. Authentik reads the SP's endpoint, binding, and certificates directly from that metadata.

The benefit of metadata: values prone to typos — entity ID, ACS URL, certificates — transfer automatically and accurately. Some applications don't support metadata export; for those, manual filling is needed by reading their documentation.

#Popular SP Case Studies

For GitLab, you install an OmniAuth block in /etc/gitlab/gitlab.rb pointing to the Authentik metadata. GitLab takes its ACS URL and entity ID from the application side, while the IdP certificate comes from the Authentik metadata — again, metadata removes most of the manual work:

gitlab.rb — OmniAuth SAML block

gitlab_rails['omniauth_enabled'] = true
gitlab_rails['omniauth_allow_single_sign_on'] = ['saml']
gitlab_rails['omniauth_auto_link_saml_user'] = true
gitlab_rails['omniauth_providers'] = [
  {
    name: 'saml',
    label: 'authentik',
    args: {
      assertion_consumer_service_url: 'https://gitlab.example.com/users/auth/saml/callback',
      idp_cert_fingerprint: '4E:1E:CD:67:4A:67:5A:E9:6A:D0:3C:E6:DD:7A:F2:44:2E:76:00:6A',
      idp_sso_target_url: 'https://authentik.example.com/application/saml/gitlab/',
      issuer: 'https://gitlab.example.com',
      name_identifier_format: 'urn:oasis:names:tc:SAML:2.0:nameid-format:persistent',
      attribute_statements: {
        email: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress'],
        first_name: ['http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name'],
        nickname: ['http://schemas.goauthentik.io/2021/02/saml/username']
      }
    }
  }
]

On the Authentik side, the ACS URL is set to https://gitlab.example.com/users/auth/saml/callback, the Audience to https://gitlab.example.com, and the recommended binding is Post — some GitLab versions have problems with the Redirect binding because the assertion URL gets too long.

For Nextcloud, install the user_saml app from the app store, choose One Login mode, then paste the IdP metadata. Set property mappings so Authentik attributes (username, email, name, groups) flow into the Nextcloud user. Nextcloud uses the uid attribute to match users.

For Google Workspace, open Apps → Web and mobile apps → Add app → Custom SAML app, then upload the IdP XML metadata. In the attribute mapping menu, match the Authentik SAML attributes (firstname, lastname, email) with what Authentik sends.

For AWS SSO (IAM Identity Center), choose Enable external identity provider, upload the Authentik IdP metadata as IdP metadata, then configure the NameID attribute and format to match Authentik's persistent value.

#Attribute Mapping to Match SP Expectations

Often the SP demands attributes not available in the built-in mappings. For example, an SP requests a role attribute for access control:

SAML property mapping — role from user status

return "admin" if request.user.is_superuser else "user"

SAML property mapping — role from group membership

return "admin" if ak_is_group_member(request.user, name="admin") else "member"

Create a mapping with the SAML Attribute Name the SP asks for, select it on the provider, and test with a login. A property mapping returning None is skipped by Authentik — so an expression that finds no value doesn't break the assertion.

#SAML Troubleshooting

SAML is hard to debug because its messages are wrapped in XML and often pass through several redirects. The most important tool: the SAML tracer browser extension (available for Firefox and Chrome). It displays all SAML requests and responses on every login — including the assertion, attributes, and signature.

The most frequent problems:

• Signature validation error — the certificate on the SP side doesn't match Authentik's signing certificate. Make sure the public key the SP imported is correct and not expired.
• Audience/Entity ID mismatch — the Audience value in Authentik doesn't equal the SP's entity ID. A single-character typo makes the SP reject the assertion.
• Time sync — a SAML assertion contains validity timestamps. The Authentik server and SP must have minimal time difference. Use NTP:

timedatectl status
ntpq -p

• Relay state — the parameter that carries the user back to the original page. If it's lost, the user ends up on the SP's front page after login. Check with SAML tracer whether the relay state is carried across every hop.
• Attributes not appearing — check whether the SP demands attributes Authentik doesn't send, or whether the attribute names differ. SAML tracer shows the raw assertion so you can compare it with what the SP requests.
• NameID format mismatch — the SP requests a specific format; make sure the Authentik NameID policy produces that format.

#Testing SP Integrations

Once metadata and attributes are prepared, test with a calm sequence:

1. Open the SP application and choose the SAML login option (for example the Sign in with Authentik button in GitLab).
2. Log in at the Authentik portal — you should be redirected back to the application without a second login.
3. Open SAML tracer and inspect the last assertion: NameID, attributes, and validity period.
4. Check the user that appears in the application — email, name, and groups must match the mappings you created.

A test strategy that limits risk: start with one test user and one application, confirm all attributes are correct, then grant access to the whole organization. Also resync keys and metadata on both sides every time the Authentik certificate changes — certificate changes are the most fragile moment for "suddenly broken" SAML integrations.

#Closing

This episode connected the Authentik SAML provider with real SPs: two-way metadata exchange, case studies for GitLab, Nextcloud, Google Workspace, and AWS, attribute mapping via custom property mappings, and troubleshooting techniques with SAML tracer, signature checks, audience mismatches, and time synchronization.

The pattern to carry forward: metadata minimizes manual errors, attributes must match the names the SP requests, and the raw assertion in SAML tracer is the source of truth for diagnosis. In episode 16, we reverse the connection direction — from Authentik as an IdP to Authentik as a client: OAuth sources (social login), connecting GitHub, Google, and Discord as login sources. See you there!