Learn Authentik - SAML Provider Configuration

#Introduction

The proxy provider phase is complete: in episodes 12 and 13, you protected applications via forward auth. Starting with this episode, we enter a new phase of a different nature: SAML. If forward auth protects applications that have no login system of their own, SAML connects Authentik with enterprise applications that have their own login system and demand a federation standard.

OIDC (covered in phase 3) is the modern JSON-based authentication standard. SAML 2.0 is its XML-based predecessor — older, more verbose, but still a mandatory standard in many enterprise products: Google Workspace, AWS, Salesforce, and Office 365. In this episode, you turn Authentik into a SAML Identity Provider (IdP).

#IdP and SP: Two Different Roles

In SAML, there are always two parties:

• Identity Provider (IdP) — the party that verifies identity and issues the assertion. In our context: Authentik.
• Service Provider (SP) — the application that uses the assertion to recognize the user. Examples: GitLab, Nextcloud, Google Workspace.

The exchange is simple: the user opens the application (SP), the SP throws the question "who is this user?" to the IdP, the user logs in at Authentik, Authentik issues an assertion — a signed XML document containing the user's identity — then the SP validates the signature and accepts the user.

Analogy: the SP is the receptionist asking visitors for a stamped ID card. The IdP is the civil registry office that issues it. The receptionist doesn't know the visitor personally — it only trusts the civil registry's signature.

#Creating a SAML Provider

In the Authentik UI, navigate to Applications → Applications → New Application, choose the SAML Provider type, then fill in the following settings:

The ACS URL and Audience come from the integrated application — they aren't values you decide yourself. This is the part most often mixed up: you don't guess values, you read them from the SP documentation or metadata.

#Binding: POST vs Redirect

Binding determines how the assertion is transported over HTTP:

• HTTP POST — the assertion is sent in the body of a POST form. Safer for large data like signed XML assertions, because it isn't constrained by URL length.
• HTTP Redirect — the assertion is sent as a URL query parameter. Practical, but limited by URL length and less suitable for large assertions.

Most modern applications support POST; it's also what Authentik recommends. Choose POST unless the SP demands Redirect.

#Signing Certificates

SAML relies on cryptographic trust. The assertion must be signed so the SP is sure it genuinely came from Authentik and wasn't modified in transit.

The steps in Authentik: create a key pair in Certificates (or use an existing one), then select it as the provider's Signing certificate. Two related algorithms:

• Signing algorithm — the cryptographic signing method, for example RSA-SHA256.
• Digest algorithm — the hash function used in the signature process, for example SHA-256.

#NameID: The User Identity in the Assertion

NameID is the user's unique identifier in the assertion — a kind of stable master number that doesn't change even when other attributes change. Supported formats:

• persistent — a stable hash identity of the user. The best default choice.
• transient — a session-based identity, changes on every login.
• emailAddress — uses the user's email as the NameID. Risky if users are free to change their email.
• windowsDomainQualifiedName — a UPN-based identity, relevant in Active Directory environments.

Authentik lets you choose a property mapping that produces the NameID via the NameID property mapping field. If left empty, the NameID policy from the SP's request applies.

#Metadata: The Bridge of Trust

SAML doesn't demand manually copying values if both parties provide metadata — an XML document containing endpoints, bindings, certificates, and unique identifiers.

Authentik's IdP metadata is available at:

SAML provider metadata URL

https://authentik.example.com/application/saml/<application-slug>/metadata/

Replace <application-slug> with the slug of the SAML application you created. A snippet of the metadata looks like this:

IdP metadata snippet (simplified)

<EntityDescriptor entityID="https://authentik.example.com/application/saml/gitlab/metadata/">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" ...>
    <KeyDescriptor use="signing">
      <KeyInfo><X509Data><X509Certificate>...</X509Certificate></X509Data></KeyInfo>
    </KeyDescriptor>
    ...
  </SPSSODescriptor>
</EntityDescriptor>

In the UI, metadata can be downloaded via the Download button on the provider page, or accessed through the Metadata tab. Conversely, if the SP provides XML metadata, Authentik can create a provider automatically from that metadata — choose the SAML Provider from Metadata type when creating a provider.

#Property Mapping for Attributes

The assertion can carry additional attributes beyond NameID — email, name, groups — via property mappings. Authentik provides built-in mappings for email, username, name, groups, and UID. If the SP demands a special format, create a custom mapping. Example of an SP that wants givenname and surname separated:

SAML property mapping — givenname

return request.user.name.split(" ", 1)[0]

SAML property mapping — surname

return request.user.name.rsplit(" ", 1)[-1]

Set the SAML Attribute Name to what the SP expects (for example http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname), then select that mapping on the provider.

#When SAML, When OIDC?

Rule of thumb: for new applications and modern integrations, choose OIDC. For enterprise applications that only support SAML, use SAML. Don't choose SAML just because it's "more secure" — both are secure when configured correctly.

#Closing

This episode configured Authentik as a SAML IdP: understanding the IdP and SP roles, filling in the ACS URL, Audience, and POST binding, preparing the signing certificate along with the signing and digest algorithms, choosing a stable NameID policy, exporting the IdP metadata via URL, mapping attributes with property mappings, and deciding when SAML rather than OIDC.

In episode 15, you'll use this foundation to connect real SPs — GitLab, Nextcloud, Google Workspace, and AWS — through metadata exchange, then walk through the SAML troubleshooting that most often makes people give up. See you there!