Keycloak as a SAML Service Provider: The Complete Guide

Last updated: May 2026

When Keycloak acts as a SAML Service Provider, it brokers authentication from an external SAML Identity Provider by adding a “SAML v2.0” identity provider entry in the admin console. You exchange metadata documents with the upstream IdP, configure NameID format, enable assertion signing and encryption, and Keycloak issues its own session tokens to your downstream applications. This pattern is called identity brokering: your apps speak OIDC or SAML to Keycloak, and Keycloak handles the SAML exchange with the upstream IdP behind the scenes.

This guide covers everything you need to stand up that configuration correctly: SP vs. IdP role distinctions, when to choose SAML brokering, the end-to-end admin console walkthrough using Okta as an example IdP, metadata and entity ID details, NameID and binding options, assertion signing and encryption, the first-login flow and account linking, attribute mapping, testing, and a troubleshooting reference for the most common SP errors.

SP vs. IdP Roles in SAML

SAML 2.0 defines two distinct roles in every authentication exchange:

• Identity Provider (IdP): The authority that authenticates the user and issues a signed SAML Assertion. Examples: Okta, Microsoft Entra ID, Google Workspace, ADFS.
• Service Provider (SP): The party that consumes the assertion and grants the user access. In identity brokering, Keycloak is the SP.

It is common to confuse the two because Keycloak can play both roles simultaneously: it acts as an IdP toward your downstream applications while acting as an SP toward an upstream SAML IdP. This guide focuses exclusively on Keycloak’s SP role.

When to Use SAML Brokering

SAML brokering is the right pattern when:

• Your organization’s authoritative user store lives in an enterprise IdP (Okta, Entra ID, ADFS) that speaks SAML, but your applications are built against OIDC or a different SAML endpoint.
• You need to aggregate multiple upstream IdPs under a single Keycloak realm without modifying application code.
• You want to enrich or transform SAML assertions (add roles, normalize attributes, enforce MFA step-up) before forwarding credentials to applications.
• You are migrating from a direct SAML integration to OIDC and need a bridge during transition.

If you are configuring Keycloak to issue SAML assertions to a downstream application — not consume them from an upstream IdP — you want the client SAML configuration, not the identity provider configuration covered here.

Prerequisites

Before starting:

• Keycloak 17+ (Quarkus distribution). This guide uses Keycloak 26.x. The legacy WildFly distribution (Keycloak 16 and earlier) uses a URL path prefixed with /auth/ — that prefix is absent in all current Keycloak versions.
• Administrative access to both the Keycloak Admin Console and the upstream SAML IdP.
• The IdP metadata URL or XML file (contains entity ID, SSO endpoint URL, and signing certificate).
• HTTPS configured for your Keycloak instance. Never run a SAML SP over plain HTTP in any environment beyond local testing.

SAML SP Metadata and the Descriptor URL

Before touching the admin console, understand what Keycloak publishes as its SP metadata. In Keycloak 17 and later, the SP (identity provider broker) metadata descriptor is available at:

https://{KEYCLOAK_URL}/realms/{realm}/protocol/saml/descriptor

Keycloak 16 and earlier (legacy WildFly) used:

https://{KEYCLOAK_URL}/auth/realms/{realm}/protocol/saml/descriptor

The /auth/ prefix is a legacy path and does not exist in current Keycloak. If your upstream IdP requires you to supply a metadata URL, give it the first form.

You can also find this URL in the admin console: Realm Settings > General > Endpoints > SAML 2.0 Identity Provider Metadata.

The descriptor document contains:

• The SP entity ID (https://{KEYCLOAK_URL}/realms/{realm})
• The Assertion Consumer Service (ACS) URL for the specific IdP alias
• Supported NameID formats
• The realm’s signing certificate

SP Entity ID

Keycloak’s entity ID when acting as a SAML SP is the realm URL:

https://{KEYCLOAK_URL}/realms/{realm}

This value must be registered exactly in the upstream IdP’s application/service provider configuration (called “Audience URI” in Okta, “Identifier” in Entra ID, “Entity ID” in ADFS). A mismatch between the entity ID in the SAML Assertion’s <Audience> element and the realm URL is one of the most common SP configuration errors.

The ACS URL (where the IdP POSTs the assertion after authentication) is:

https://{KEYCLOAK_URL}/realms/{realm}/broker/{idp-alias}/endpoint

where {idp-alias} is the alias you assign to the identity provider entry in Keycloak (e.g., okta, entra, adfs).

Adding a SAML v2.0 Identity Provider in Keycloak

This section walks through the full configuration using Okta as the upstream IdP. The same steps apply to any SAML 2.0 IdP.

Step 1: Create the Identity Provider Entry

1. Open the Keycloak Admin Console and select your realm.
2. Navigate to Identity Providers.
3. Click Add provider and select SAML v2.0.
4. Set the Alias field. This value becomes part of the ACS URL, so choose a stable, lowercase identifier (e.g., okta). The alias cannot be changed later without reconfiguring the IdP.
5. Optionally set a Display name (shown to users on the login page button, e.g., “Sign in with Okta”).

Step 2: Import IdP Metadata

In the Import config section you have two options:

Option A: Import from URL (recommended)

Paste the metadata URL from your IdP. Okta provides this under Sign-On > Metadata URL; Entra ID provides it as the Federation Metadata Document URL. Click Show metadata or Import to auto-populate:

• Single Sign On Service URL (the IdP’s SSO endpoint)
• Single Logout Service URL
• Validating certificate (the IdP’s public signing certificate)

Option B: Import from file

Download the IdP metadata XML and upload it. Useful when the IdP is not reachable from the Keycloak server.

After import, verify that the SSO Service URL and certificate fields are populated before saving.

Step 3: Configure the IdP Side

In Okta (or your IdP), create a SAML 2.0 application with the following values derived from your Keycloak instance:

IdP Field	Value
Single Sign-On URL (ACS URL)	https://{KEYCLOAK_URL}/realms/{realm}/broker/{alias}/endpoint
Audience URI (Entity ID)	https://{KEYCLOAK_URL}/realms/{realm}
Name ID Format	EmailAddress or Unspecified (must match Keycloak’s NameID policy)

Select Use this for Recipient URL and Destination URL in Okta. Assign test users to the application before testing.

For Entra ID-specific steps see our dedicated guide.

NameID Format

The NameID is the primary identifier Keycloak uses to create or locate a local user record after assertion validation.

In the Keycloak identity provider settings, the Name ID Policy Format options include:

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress — suitable when the IdP sends the user’s email as the subject.
• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent — an opaque, durable identifier; preferred for avoiding PII in the subject.
• urn:oasis:names:tc:SAML:2.0:nameid-format:transient — session-scoped; not suitable as a stable user identifier.
• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified — lets the IdP decide; use when the IdP does not advertise a specific format.

Set Force Name ID Format to ON only if you want Keycloak to enforce the format in its AuthnRequest regardless of what the IdP advertises.

A NameID format mismatch between the AuthnRequest and the Assertion response is a frequent source of login failures. When in doubt, set Keycloak to unspecified first to confirm authentication works, then tighten the format.

Assertion Signing, Encryption, and Validation

Validating the IdP Signature

By default, Keycloak requires the SAML Assertion to be signed by the IdP. The validating certificate imported from IdP metadata is used for this. Key settings in the Keycloak identity provider configuration:

• Validate Signatures: ON (strongly recommended; disable only during initial debugging on a non-production instance)
• Validating X.509 Certificate: auto-populated from metadata import; verify it matches the IdP’s current signing certificate

If the IdP rotates its signing certificate, you must update this field. Use the SAML Decoder to inspect a live assertion and confirm which certificate was used to sign it.

Signing AuthnRequests

Keycloak can sign the AuthnRequest it sends to the IdP. This is required by some IdPs as additional request authenticity verification:

• Want AuthnRequests Signed: matches what the IdP’s metadata declares
• Signature Algorithm: use RSA_SHA256. RSA_SHA1 is deprecated and rejected by many modern IdPs.

The signing key pair is managed under Realm Settings > Keys. For production, rotate keys on a 12-24 month schedule.

Assertion Encryption

If the IdP supports assertion encryption, enable it to protect attribute values in transit:

• Want Assertions Encrypted: ON
• Provide the Keycloak realm’s encryption certificate to the IdP so it can encrypt the assertion

Encryption adds latency and complexity; use it when compliance requirements mandate it or when assertions contain sensitive attributes.

SP-Initiated vs. IdP-Initiated Flow

SP-Initiated (standard)

The user starts at a Keycloak-protected application or the Keycloak account console:

1. User is redirected to the Keycloak login page.
2. User clicks “Sign in with Okta” (or the identity provider button).
3. Keycloak generates a SAML AuthnRequest and sends it to the IdP via HTTP Redirect or POST binding.
4. The IdP authenticates the user and returns a signed SAML Assertion via HTTP POST to the ACS URL.
5. Keycloak validates the signature, checks assertion conditions (NotBefore, NotOnOrAfter, Audience), and creates or maps a local user.
6. Keycloak establishes its own session and redirects the user to the application.

IdP-Initiated Flow

When the session originates at the IdP portal and the assertion is pushed to Keycloak without a prior AuthnRequest, this is an IdP-initiated flow. Keycloak supports this but it introduces security tradeoffs around missing InResponseTo correlation. For a detailed treatment, see Bridging IdP-Initiated SAML to OIDC with Keycloak.

First-Login Flow and Account Linking

On the first successful assertion validation, Keycloak must decide what to do with the authenticated identity. This is controlled by the First Login Flow setting on the identity provider entry (default: first broker login).

The default first broker login flow:

1. Checks if a Keycloak user with a matching email or username already exists.
2. If a match is found, prompts the user to confirm account linking (or links automatically, depending on configuration).
3. If no match is found, creates a new Keycloak user and optionally prompts for missing required fields.

On subsequent logins, Keycloak looks up the federated identity record and skips the linking prompt.

If your IdP does not include email or other required attributes in the assertion, Keycloak will prompt the user to supply them on first login. Automating this requires configuring attribute mappers, covered in the next section.

Attribute Mapping

SAML Assertions typically carry user attributes (email, first name, last name, groups, roles) as <AttributeStatement> elements. Without explicit mappers, these attributes are not automatically written to Keycloak user fields.

Mappers are configured under Identity Providers > {your-idp} > Mappers > Add Mapper.

The most common mapper type for SP brokering is Attribute Importer, which reads a named SAML attribute from the assertion and writes it to a Keycloak user property or custom attribute.

Example mappers for the Okta integration:

SAML Attribute Name	User Attribute	Notes
email	email	Map Okta username as email for uniqueness
firstName	firstName	Standard given name
lastName	lastName	Standard surname

Attribute mapping configuration is covered in full detail — including multi-valued attributes, role mappers, and debugging with SAML Tracer — in our dedicated guide: Attribute Mapping when using Keycloak as a SAML SP.

Testing the Integration

Once both sides are configured:

1. Open a Keycloak-protected application or navigate to https://{KEYCLOAK_URL}/realms/{realm}/account.
2. Click the identity provider button (e.g., “Sign in with Okta”).
3. Authenticate at the IdP.
4. Keycloak receives the assertion, validates it, and creates a local user session.
5. Verify the user record in Users > {username} in the admin console. Confirm federated identity is listed under Identity Provider Links.

Tooling for inspection:

• Use the SAML Decoder to paste and decode raw Base64-encoded SAML Responses from browser network logs.
• Use the Firefox SAML Tracer extension for live request/response inspection.
• Enable Keycloak’s org.keycloak.broker.saml logger at DEBUG level for detailed server-side assertion processing logs.

For assertion validation during testing, check:

• Issuer matches the IdP’s entity ID
• Audience in <AudienceRestriction> matches https://{KEYCLOAK_URL}/realms/{realm}
• NotBefore and NotOnOrAfter conditions are valid relative to current server time
• Signature verifies against the IdP’s configured certificate

Troubleshooting Common SP Errors

Invalid Signature

Symptom: Keycloak logs Unable to validate SAML assertion signature or the user sees a generic login failure.

Causes:

• The IdP rotated its signing certificate and the new certificate has not been updated in the Keycloak identity provider entry.
• The assertion is signed with a certificate the IdP is not advertising (e.g., a secondary cert during rollover).
• Validate Signatures is enabled but the assertion is unsigned (some IdPs sign only the response envelope, not the inner assertion).

Fix: Copy the current signing certificate from the IdP’s metadata URL, update Validating X.509 Certificate in the Keycloak identity provider settings, and re-test. Use the SAML Decoder to confirm which certificate was used to sign the assertion.

NameID Mismatch

Symptom: Authentication succeeds at the IdP but Keycloak cannot map the user or creates duplicate accounts.

Causes:

• The NameID format in the Keycloak AuthnRequest does not match what the IdP sends.
• The IdP sends a transient NameID but Keycloak is trying to use it as a persistent user identifier.

Fix: Set Name ID Policy Format to unspecified in Keycloak to relax the constraint, or align it precisely with what the IdP advertises. Confirm the actual NameID value using SAML Tracer or the SAML Decoder.

Clock Skew

Symptom: Assertion expired or NotBefore condition not met in Keycloak logs, even though authentication just completed.

Causes: The Keycloak server clock or the IdP server clock is out of sync. SAML conditions use absolute timestamps, and even a 2-minute difference can cause failures if the IdP issues short-lived assertions.

Fix: Ensure both servers use NTP and are synchronized. In Keycloak, set the Allowed Clock Skew value under the identity provider’s settings to tolerate small drift (60 seconds is a common starting point).

RelayState Not Preserved

Symptom: After successful IdP authentication, the user lands on the Keycloak account page or a generic redirect instead of the original application URL.

Causes: The IdP is not passing the RelayState parameter back to Keycloak’s ACS endpoint. RelayState carries the original authentication context; without it, Keycloak cannot resume the session.

Fix: Confirm the IdP is configured to pass RelayState through the SSO response. Verify the ACS URL in the IdP includes RelayState in the list of accepted parameters. Some IdPs have an explicit “Pass through RelayState” toggle.

Audience Restriction Failure

Symptom: Assertion is not valid for audience in Keycloak server logs.

Causes: The <Audience> element in the SAML Assertion contains a value that does not match the Keycloak realm URL exactly (including scheme, host, and path).

Fix: Verify the Audience URI (SP Entity ID) in the IdP’s SAML application matches https://{KEYCLOAK_URL}/realms/{realm} character-for-character, including no trailing slash mismatch.

Security Best Practices

A few production checklist items beyond the defaults:

• Enable Sign Assertions and Sign Documents on the IdP side where possible.
• Use POST binding for the ACS URL. Redirect binding passes the assertion as a URL query parameter, which is logged by proxies and web servers.
• Set assertion NotOnOrAfter to a short window (5 minutes is standard) and configure the IdP accordingly.
• Rotate the Keycloak realm signing key pair on a schedule and update the SP metadata at the IdP after each rotation.
• Add a reverse proxy (e.g., Nginx) in front of Keycloak to handle rate limiting and DDoS mitigation.
• Enable RBAC and audit logging so every brokered authentication event is captured.
• For cross-protocol brokering (SAML upstream, OIDC downstream), see CORS configuration guidance to avoid client-side errors.
• Review known SAML exploit mitigations to harden your Keycloak deployment against signature wrapping and XML injection attacks.

Frequently Asked Questions

What is the difference between an IdP and an SP in SAML?

An Identity Provider (IdP) is the system that authenticates the user and issues a signed SAML Assertion containing the authentication result and user attributes. A Service Provider (SP) is the system that receives and validates that assertion to grant the user access. When Keycloak is acting as a SAML SP, it trusts an external IdP like Okta or Entra ID to authenticate users and accepts their assertions to establish a Keycloak session.

What is the Keycloak SAML metadata URL?

In Keycloak 17 and later (Quarkus distribution), the SP metadata descriptor URL is https://{KEYCLOAK_URL}/realms/{realm}/protocol/saml/descriptor. You can also find this link in the admin console under Realm Settings > General > Endpoints. In Keycloak 16 and earlier (legacy WildFly), the same path required an /auth/ prefix: https://{KEYCLOAK_URL}/auth/realms/{realm}/protocol/saml/descriptor — that prefix does not exist in current versions.

Why is my SAML assertion signature invalid in Keycloak?

The most common cause is a certificate mismatch: the IdP signed the assertion with a certificate that does not match the validating certificate stored in the Keycloak identity provider entry. This typically happens after the IdP rotates its signing certificate. Paste the Base64-encoded assertion into the SAML Decoder to identify the signing certificate, then update the Validating X.509 Certificate field in Keycloak to match.

What is the ACS URL for Keycloak’s SAML SP?

The Assertion Consumer Service (ACS) URL where the IdP should POST the SAML Assertion is https://{KEYCLOAK_URL}/realms/{realm}/broker/{idp-alias}/endpoint. The {idp-alias} corresponds to the alias you set when adding the identity provider in Keycloak. This URL is also displayed in the Keycloak admin console in the identity provider’s Redirect URI field.

Does Keycloak support IdP-initiated SAML SSO as a Service Provider?

Yes, Keycloak accepts IdP-initiated SAML Responses (assertions pushed without a prior AuthnRequest) at the same ACS endpoint. However, IdP-initiated flows do not carry the InResponseTo correlation ID, which weakens replay attack protection. Keycloak allows this by default but it can be disabled. If your use case involves an IdP portal launching users into OIDC-backed applications, see Bridging IdP-Initiated SAML to OIDC with Keycloak for a secure conversion pattern.

Conclusion

Configuring Keycloak as a SAML Service Provider is the standard approach for connecting an enterprise SAML IdP to a Keycloak realm without rewriting application authentication code. The core steps are consistent regardless of which IdP you use: add a SAML v2.0 identity provider entry with the IdP’s metadata, register Keycloak’s realm URL as the entity ID and the broker endpoint as the ACS URL on the IdP side, align NameID format, enable assertion validation, and configure attribute mappers to populate user fields automatically.

For the attribute mapping configuration in depth, see Attribute Mapping when using Keycloak as a SAML SP. For security hardening, review SAML exploit mitigations for Keycloak.

If you would rather not manage Keycloak infrastructure yourself, Skycloak provides fully managed Keycloak hosting with high-availability clusters, automated upgrades, and support — so you can focus on the integration, not the operations.