Keycloak as a SAML source in authentik

Keycloak as a SAML source in authentik: what the federation does

authentik can accept Keycloak as a SAML identity provider, so users sign in once while applications move over in stages. If your Keycloak realm is today's login authority, you do not need to re-create its users in authentik to introduce authentik. The federation makes Keycloak the upstream identity provider: a user starts at authentik, is redirected to Keycloak to authenticate, and comes back with a SAML assertion that authentik uses to establish a session. The supported method is authentik's SAML source for an external identity provider, and the authentik Keycloak source guide documents the steps. Keycloak remains the authority for its own users, including their passwords, MFA and realm policies, for as long as the two systems run in parallel.

This arrangement suits teams that are running both systems at once: Keycloak still serves the applications that have not moved, while authentik takes over the ones being migrated or newly onboarded. Because the trust relationship is defined by signed SAML messages, the first real work is not in the authentik user interface. It is in agreeing which system signs and which system verifies, and that agreement has to hold in both directions. Confirm with your own Keycloak administrators which realm and client will act as the identity provider for authentik, and who owns certificate renewal on each side before anything goes into production.

The key decision is how long Keycloak stays the upstream authority. Each application you move to authentik should be tested against a clear answer to who owns its user attributes, group membership and logout behavior during the overlap. Ask your team to document which attributes authentik receives from Keycloak, which ones it stores locally, and which applications still depend on Keycloak directly. Those answers determine the sequence of the phased move and the point at which the federation can be retired.

What you need before configuring the Keycloak SAML source

Most failed federations trace back to a missing prerequisite rather than a wrong setting. The items below cover both systems, the network path between them, and the certificates that will sign and encrypt SAML messages. Check each one before exporting a single certificate.

An authentik release on a supported line

Confirm that your authentik deployment runs a version on a line that receives security fixes. The authentik security policy lists 2026.5.x and 2026.8.x as supported, and the project announces security releases at least 24 hours in advance. Check the exact version you run, since authentik releases on its own cadence and an older line may lack the source options your guide expects. Plan to re-verify the version on the day you start.

Admin access to the Keycloak realm

You need an account with rights to manage the target realm, its clients and its signing keys, not only to log in to users. Confirm you can view the realm's SAML metadata and change client settings in the admin console. If a separate team owns Keycloak, agree in writing who makes the client changes and who approves them. Keep a copy of the current client configuration so you can revert it during a phased move.

A Keycloak release you can verify

Record the exact Keycloak version running in your environment before you write any configuration. The current release is 26.8.1, published October 13, 2026, but your production realm may run an earlier version. Check the version in the admin console or your deployment manifest, and confirm that your change process covers the minor release cadence. Settings and screens can differ between releases, so match the steps in the guide to your version.

Two-way network reachability

SAML federation depends on browsers and back-channel calls moving in both directions. Users' browsers must reach authentik and Keycloak, and the authentik server must reach the Keycloak metadata and endpoints it uses. Keycloak must reach the authentik metadata URL and assertion consumer endpoint. Test each path from the host that needs it, including any proxy, firewall or DNS split between internal and external names, since a name that resolves correctly in one network can fail in another.

TLS certificates on both endpoints

Decide which hostnames both systems will present and confirm that each has a valid certificate chain that clients trust. The SAML metadata you exchange embeds the hostnames, so a change of name later means re-exchanging metadata and signing certificates. Confirm who issues and renews each certificate, and where the authentik and Keycloak certificate private keys are stored. Note the expiry dates, because an expired signing certificate breaks sign-in for every user at once.

A plan for signing certificates

The federation starts by exporting the signing certificates of Keycloak and authentik so each side can verify the other's signatures. Decide which certificate key pair each system will use, who holds the export, and how the other side receives it. Document the certificate fingerprints in your change record. A rotation plan matters as much as the first exchange, because each side must accept the new certificate before the old one is retired.

How to configure the Keycloak SAML source in authentik step by step

This sequence connects an existing Keycloak realm to authentik over SAML so that each side verifies the other's signed messages and a user can complete one login from Keycloak through authentik.

Export the Keycloak and authentik signing certificates
The administrator of the Keycloak realm exports the realm signing certificate from the Keycloak admin console, and the authentik administrator exports the certificate authentik uses to sign SAML requests. Each side needs the other's certificate so it can check signatures on assertions and requests. Confirm that you have exported the certificate from the correct realm and the correct authentik certificate pair, and record the certificate expiry dates so renewal can be scheduled. The step is done when both certificate files are stored in the change record and each administrator can open the other's file.
Confirm the entity ID and ACS values
Agree on the SAML entity ID for the Keycloak realm and the assertion consumer service (ACS) URL that authentik will expose for this source. Keycloak and authentik must use identical strings for the entity ID, and the ACS URL must match the public address of your authentik server exactly, including scheme and path. Write both values down before either side is configured, because a mismatch here is the most common reason the first login fails. The step is done when both administrators have signed off on the two values and they match what each side will display.
Create the SAML source in authentik
In the authentik admin interface, create a new SAML source and enter Keycloak's identity provider details, either by importing Keycloak's SAML metadata from the realm descriptor or by entering the SSO endpoint, the signing certificate and the issuer manually. Set the binding and signing options to match what Keycloak will send, and attach the Keycloak signing certificate exported earlier. The step is done when the source saves without validation errors and the source shows the Keycloak issuer value you confirmed in the previous step.
Create the matching SAML client in Keycloak
In the Keycloak admin console, create a SAML client for authentik using the entity ID and ACS URL agreed earlier, and import the authentik signing certificate. Enable signed assertions and signed responses if your security policy requires them, and make sure the client's name ID format matches what authentik expects. Keep the client scoped to the realm users who should reach authentik. The step is done when the client appears in the realm's client list with the same entity ID that authentik shows for its SAML service provider.
Map the NameID and user attributes
Decide which Keycloak attribute will serve as the NameID and which attributes authentik needs, such as email address, username and display name, then map them in the SAML source's property mappings. Test the mapping with a sample user whose attributes you know, because a missing or misnamed attribute usually produces an account with a blank field rather than a visible error. Check that the NameID value is stable for each user so repeat logins link to the same authentik account. The step is done when the attribute preview for the test user shows the expected username, email and name values.
Test one login end to end
Open a private browser session, start at the authentik login page, choose the Keycloak source, and sign in with a test user from the Keycloak realm. Watch the browser redirects and confirm that the SAML response returns to the authentik ACS URL and that authentik creates or links the user as expected. If the login fails, check the signature validation and entity ID messages in the authentik and Keycloak logs before changing any setting. The step is done when the test user lands in authentik with the correct identity, and the signed assertion is accepted without errors.
Run both sources during the phased move
Keep the Keycloak source enabled in authentik alongside any existing sign-in path while you move applications across in batches, so users can keep signing in while you test each application. Confirm which applications still rely on Keycloak directly and which now use authentik, and record the date of each change. Before the cutover, ask the team that operates Keycloak to confirm its upgrade plan, because the Keycloak release cadence and any breaking changes affect the certificates and client settings you configured. The step is done when the list of applications and their sign-in path is current and every user group has been tested on the new path.

How authentik trusts Keycloak assertions in the federation

authentik trusts a Keycloak assertion only when its signature verifies against the certificate you exported from the Keycloak realm. When a user starts a login, authentik redirects the browser to Keycloak with a SAML AuthnRequest. Keycloak signs the response it returns, and authentik checks that signature with the Keycloak signing certificate stored on the SAML source. The reverse trust works the same way: Keycloak checks authentik's signature on requests with the authentik signing certificate configured on the Keycloak client. Because each side holds only the other's public certificate, both certificates must be exchanged before any test login, and the Keycloak client must be configured to expect the same signing material authentik presents.

Identity matching happens after the signature check succeeds. The entity ID on the source and the one configured on the Keycloak client must match exactly, character for character, along with the assertion consumer service URL that Keycloak posts responses to. A trailing slash, a different hostname or an http URL where the deployment expects https causes Keycloak to reject the request or authentik to discard the response. Once the assertion is accepted, authentik uses the NameID and the attributes Keycloak released to create a new local user or link the response to an existing one, so the attribute and NameID mappings deserve the same review as the certificates. Confirm the exact entity ID and ACS values in the authentik and Keycloak documentation for your versions before you copy them.

Two failure modes account for most broken logins after the first successful test. The first is certificate rotation: when Keycloak regenerates its realm signing key, authentik keeps verifying against the old certificate and every assertion fails until the source is updated. Plan a rotation step, record who owns it, and re-export the certificate before the old key expires. The second is clock skew: SAML assertions carry validity windows, and if the authentik host and Keycloak disagree on time, valid assertions look expired or not yet valid. Synchronize both servers with NTP and check time sources during the pilot, not after go-live.

Mapping Keycloak realm attributes to authentik user fields

This table lists the identity fields you must decide on before creating the SAML source, from NameID to group attributes and the matching rule for existing accounts. Read each row as a decision: settle the Keycloak side in the realm first, then set the matching authentik side so both systems agree on who a user is. The main takeaway is that attribute names are not fixed by either product, so confirm them in your own realm before testing.

Identity field	Decision to make	Keycloak side to confirm	authentik side to confirm
SAML NameID	Choose the identifier Keycloak sends as the subject and its format, such as persistent or email format.	The NameID format and value configured on the Keycloak SAML client, and whether it is the username, email or a stable ID.	Which NameID format the authentik SAML source expects, and whether it links the subject to a user field.
Username	Decide whether authentik's username must equal the Keycloak username or can be a different stable value.	The user property used for the username and whether it can change after creation.	The attribute or NameID value mapped to the authentik username field.
Email	Decide whether email is used for matching, notification or both.	The mapper that releases the email attribute and whether the address is verified in Keycloak.	The mapping to the authentik email field and whether duplicate emails are allowed.
Display name	Decide how first and last names combine into the name shown in authentik.	Whether first name and last name are sent as separate attributes or as one name attribute.	The property mapping that builds the authentik name from the incoming attributes.
Group or role attributes	Decide which Keycloak groups or roles grant authentik groups, and whether they are only informational.	The group or role mapper, its attribute name, and whether full group paths or short names are sent.	The group mapping in the source, and whether groups are created automatically or must already exist.
Matching rule for existing accounts	Decide whether an incoming user links to an existing authentik account by username, email or another identifier, and whether linking is automatic.	Whether the same person has one Keycloak identity that is stable across realm changes.	The source's identifier and enrollment behavior, plus how you handle conflicts and users who already exist locally.
Attribute names in the assertion	Record the exact attribute names Keycloak emits so the property mappings match them.	Client mapper names and attribute names in the SAML assertion, confirmed by testing with a sample user in the realm.	Property mappings that read those names, checked against an assertion captured during a test login.

Running Keycloak and authentik side by side during a phased move

Applications that have not moved keep their existing Keycloak clients, realm roles and login flows. During the move, Keycloak remains the authoritative store for these users and their credentials, and nothing about their sign-in should change because authentik now exists. The SAML source in authentik only brings in users who sign in through authentik, so a Keycloak-only application is unaffected by the source being configured. Confirm that no client in this group has been pointed at authentik's metadata by mistake, and that Keycloak's session and logout behavior is unchanged.

Keep the realm as system of record: Do not enable writes from authentik back into Keycloak for these users.
Freeze role changes in one place: Make role and group edits in Keycloak only until the application moves.
Track the inventory: Keep a list of every Keycloak client and its status so no application is left without an owner.
Watch shared sessions: Confirm which applications share a Keycloak browser session with migrated ones, since logout in one can affect the other.
Test login after each change: Run a sign-in check for a sample user against each unmoved application.

Check that every unmoved client still has a documented owner and a known fallback before the next wave starts.

Hardening the SAML trust between Keycloak and authentik

The SAML source trusts whatever Keycloak signs, so the trust relationship is the control point. The cards below cover the client scope, signature requirements, key handling, transport security and the Keycloak clients and roles that reach authentik. Verify each setting against the Keycloak and authentik versions you run, because option names and defaults change between releases.

Scope the SAML client to the ACS URL

Create a dedicated SAML client in Keycloak for authentik and register only the authentik assertion consumer service (ACS) URL shown on the authentik source as a valid redirect. Avoid wildcard redirect patterns, which let a crafted request route a signed assertion to another endpoint. Confirm the entity ID matches the value configured in the authentik source exactly, since a mismatch will fail validation or, worse, let a second client impersonate the relationship.

Require signed assertions and responses

Decide whether Keycloak signs the full SAML response, the assertion, or both, and configure authentik to require the matching signature. Signing both is the stricter choice where your versions support it. Check how each side handles unsigned or partially signed messages, because a source that accepts unsigned input weakens the whole trust. Test with a deliberately altered assertion in a non-production realm and confirm authentik rejects it.

Protect the signing private keys

The Keycloak realm signing key and the authentik signing material are the credentials that make the federation trustworthy. Restrict admin console access to the realm keys, limit who can export or download private key material, and store any exported keys in your secrets manager rather than in tickets or shared drives. Only public certificates should move between the two systems during the exchange.

Rotate certificates on a planned schedule

Set a rotation calendar for both sides before go-live, and document who issues the new certificate, how it is delivered, and the overlap window during which both old and new certificates are accepted. Rotations that are not planned tend to break logins at the moment a certificate expires. Ask your team to confirm whether the authentik source accepts multiple signing certificates during a transition, and test that path in staging first.

Enforce TLS on both endpoints

Serve the Keycloak metadata and SSO endpoints and the authentik ACS endpoint only over HTTPS with certificates your browsers and servers trust. Metadata exchanged over plain HTTP can be altered in transit, which would change which certificate authentik trusts. Confirm the Keycloak hostname configuration is set for production so that the URLs in its metadata are the public HTTPS addresses, and review the Keycloak production configuration guide for proxy and hostname settings.

Limit which Keycloak clients and roles reach authentik

Federation exposes every user in the scoped realm unless you narrow it. Use Keycloak group or role membership to decide which users may authenticate through the SAML client, and map only the attributes authentik needs. Review assigned roles on a regular cadence, and remove the client from any realm or environment that no longer needs authentik access. Document the mapping so auditors can trace who can sign in and why.

Why the Keycloak SAML login fails and how to fix it

This table lists the failures teams most often hit when federating Keycloak into authentik over SAML, with the likely cause and the fix for each. Work through the rows in order when a login fails, because certificate and clock problems hide behind generic error pages. Most failures trace back to a mismatch between what one side expects and what the other side sends.

Failure	Likely cause	Fix
Signature validation error	The signing certificate in the authentik source is missing, expired or from a previous Keycloak key, so authentik cannot verify the assertion.	Re-export the active realm signing certificate from Keycloak and replace it in the authentik source. Confirm the realm has one active RS256 key before you export.
Signature validation error on the Keycloak side	authentik's signing certificate was not imported into the Keycloak SAML client, so Keycloak cannot verify authentik's requests.	Import the authentik signing certificate into the Keycloak client settings and confirm the client expects signed requests if authentik signs them.
Entity ID mismatch	The Keycloak client ID does not match the entity ID configured in the authentik source, or the trailing path or slash differs.	Copy the entity ID exactly from both sides and compare them character by character. Update whichever side differs from the agreed value.
ACS URL mismatch	The assertion consumer service URL registered in Keycloak points to a different host, path or binding than the one authentik uses.	Set the Keycloak client's valid redirect and ACS URL to the authentik source's ACS endpoint, using the POST binding that the source is configured to use.
Clock skew between hosts	The Keycloak and authentik hosts have drifting clocks, so assertions appear not yet valid or already expired.	Synchronize both hosts with NTP and check the time on each server before retesting. Keep the validity window in the assertion consistent with the clock tolerance you have confirmed.
Missing NameID	The Keycloak client does not send a NameID, or the NameID format does not match what the authentik source expects.	Set the NameID mapper in the Keycloak client to a stable user attribute, such as username or email, and match the NameID format on the authentik source.
Missing attributes or groups	The attribute mappers for email, name or group membership are absent from the Keycloak client, so authentik creates users without the fields it needs.	Add attribute mappers in the Keycloak client for each attribute you use in authentik's property mappings, then test with a user who holds the expected groups.
Duplicate accounts	The identifier authentik matches on (for example email or username) differs from the value Keycloak sends, so each login creates a new user.	Choose one stable identifier, align the Keycloak mapper and the authentik matching setting to it, and remove duplicate test accounts before you go live.
Redirect loop	Mixed HTTP and HTTPS URLs in the Keycloak frontend URL, reverse proxy headers or authentik external host cause the browser to bounce between schemes.	Set the public HTTPS hostname on both servers, confirm the reverse proxy forwards the original scheme and host headers, and correct any URL still using HTTP.

Questions teams ask before connecting Keycloak to authentik

How much effort does connecting Keycloak to authentik take?

The effort depends mostly on how many Keycloak clients you federate, how much attribute mapping the applications need, how complex the realm is, and how many cutover phases you run. A single realm with a handful of SAML clients and simple attributes is a small, contained change. Realms with many clients, custom protocol mappers, group-based authorization or applications that read specific claims take longer to map and verify. Ask any provider to break the work down by client count, attribute mapping and cutover phases, since those are the items that move the estimate. The Keycloak source guide begins by exchanging signing certificates, so certificate handling is a fixed early step regardless of size.

Can our own team connect Keycloak to authentik without a partner?

Yes, a team that already runs both Keycloak and authentik can do the federation work itself, because the core steps are configuration: exporting signing certificates, creating the SAML source in authentik, and setting up the matching client in Keycloak. The harder part is usually the surrounding work, such as testing every application's attribute expectations, planning the phased move and agreeing a rollback path. If your staff lacks experience with SAML metadata, signature validation or one of the two platforms, a fixed-scope engagement with written deliverables can cover the gap. DeployOpen implements, integrates and documents self-hosted platforms in your own infrastructure, and scope is agreed in writing before work starts.

What do we need from our own staff for this work?

Plan for four groups of people. Keycloak administrators need to export certificates, review realm clients and protocol mappers, and confirm which users and groups are in scope. authentik administrators create the SAML source, configure attribute mapping and manage enrollment or linking behavior for federated users. Network and certificate owners approve the certificate exchange, confirm that both platforms can reach each other's metadata and login endpoints, and manage the certificate renewal process. Application owners verify that each relying application still receives the attributes it needs. Name one person to coordinate test sign-ins and sign-off across these groups before the work starts.

How long does a phased move from Keycloak to authentik take?

No fixed duration applies, because the length of a phased move follows from your application inventory. The number of applications, how many depend on Keycloak sign-in, how many use custom claims, and how many can be tested in a non-production environment all set the pace. Running both platforms during the move is a deliberate design choice: users can keep signing in through Keycloak while applications are switched over one group at a time. Ask for a written inventory-based plan with phases, exit criteria for each phase and a rollback step for every application, rather than a single calendar date.

Does the authentik license matter for the SAML source?

The authentik pricing page lists the Open Source edition as free, and it places Enterprise-only features such as Google Workspace and Microsoft Entra ID integrations, mTLS client certificate authentication and enhanced audit logging in the Enterprise tier. Source-based federation with Keycloak is not among those listed Enterprise features, but the pricing page does not name every feature by source type, so confirm the exact edition and feature coverage with authentik before you commit. Also check the licensing of any component your design adds, because the authentik repository places code in its enterprise directory under a separate license.

What happens to the federation when we upgrade Keycloak during the move?

A Keycloak upgrade can change SAML behavior, client settings or signing configuration, so it can break the federation even when authentik does not change. Since Keycloak 26.0, the project plans four minor releases a year and says breaking changes in a minor release are opt-in, which lowers but does not remove the risk. Before any upgrade, record the current signing certificate, client settings and protocol mappers, then retest the authentik source after the upgrade. If you rotate certificates during the upgrade, repeat the certificate exchange on both sides. Keep the Keycloak upgrade and the authentik upgrade in separate change windows so that a failure can be traced to one platform.

What should we check before we start the Keycloak to authentik move?

Confirm five things first: the exact Keycloak version and the authentik version you run, the list of SAML clients and the attributes each needs, the signing certificates and their expiry dates, the users and groups that must sign in during the move, and the rollback steps for each application. Check the supported versions and security policy for authentik on its documentation before you pick a target release. Also confirm that both platforms have a staging environment where you can test sign-in without affecting production users.

How DeployOpen scopes and delivers the Keycloak to authentik federation

DeployOpen plans, implements, tests and documents the Keycloak to authentik SAML federation inside your own infrastructure, with the scope agreed in writing before work starts. The engagement covers certificate exchange, source and client configuration, and a phased period where both identity providers run side by side.

How we scope

Written scope lists each Keycloak realm, client and user population that will federate into authentik.
Scope names the authentik version, hosting model and who owns the signing certificates and their renewal.
Fixed-scope agreement sets deliverables, test criteria and the cutover conditions for each application group.

How we build

Certificate exchange and metadata verification are completed and recorded before any SAML source is enabled.
SAML source, attribute mappings and Keycloak client settings are configured and checked against the agreed design.
Test logins cover each application group, including sessions that start in Keycloak and in authentik during coexistence.

How we hand over

Documentation records the configuration, certificate locations, renewal dates and the rollback steps for each application.
Runbooks describe how to run both identity providers during the phased move and when to retire the Keycloak path.
Handover walks your platform and security teams through the configuration and the test evidence they will need later.

How we support

Ongoing support, upgrades and continuous testing are available as a retainer after handover.
Retainer coverage can include reviewing authentik and Keycloak release notes before your planned upgrades.
Ask for the support scope, response expectations and upgrade responsibilities in the written quote.

Keycloak as a SAML source in authentik