Learn Keycloak - Keycloak as a SAML IdP

#Introduction

In episode 12 you understood the SAML foundation: assertions, bindings, the SP-initiated and IdP-initiated flows, and the XML structure. Episode 13 translates that theory into real configuration: turning Keycloak on as a SAML Identity Provider. You'll create a SAML client, export metadata, configure signing and encryption keys, choose the NameID format, map attributes, then test the flow — before we hook up a real application as a service provider in episode 14.

#Keycloak's Role as an IdP

When you create a client with the SAML type in a realm, Keycloak immediately acts as the IdP for that application. This isn't a special mode; the same realm can serve OIDC and SAML clients at once. The only difference is how the application asks for it — through the XML-based SAML protocol rather than the OIDC token endpoint.

From the SP's point of view, Keycloak exposes three important things:

• Single Sign-On endpoint — where the SP points its AuthnRequest, shaped like /realms/{realm}/protocol/saml.
• Single Logout endpoint — where SLO is processed, sharing the same address.
• Metadata descriptor — the XML document describing all of the IdP's capabilities.

#Creating a SAML Client

First steps in the admin console:

1. Open the Clients tab in a realm and click Create client
2. Select Client type SAML, and fill Client ID with the SP's entity ID
3. In the Settings tab, fill Valid Redirect URIs with the application's ACS URL
4. Choose the Name ID Format agreed with the SP
5. Configure signing and encryption options per the SP's requirements
6. Save the configuration

In modern Keycloak, the client type is chosen from the Client type dropdown with the value saml. The options you'll find in the Settings tab: Sign Assertions, Sign Documents, Require Assertion Signature, Encrypt Assertions, Force POST Binding, and Assertion Signature Algorithm. Don't turn everything on without understanding it — each option must match the SP's capabilities.

Rule of thumb: always enable Sign Assertions; enable Encrypt Assertions only when the SP demands it, because encryption adds complexity to the key exchange.

#Metadata and Signing Keys

Once the client is created, Keycloak provides the complete realm metadata at the endpoint:

realms/demo/protocol/saml/descriptor

This is the document you give to the SP as a complete description of the IdP's capabilities — including the public key used to verify signatures. Its snippet looks roughly like this:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://keycloak.example.com/realms/demo">
  <md:IDPSSODescriptor WantAuthnRequestsSigned="false"
                       protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
      <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Certificate>MIIC...</ds:X509Certificate>
      </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                            Location="https://keycloak.example.com/realms/demo/protocol/saml"/>
    <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"
                            Location="https://keycloak.example.com/realms/demo/protocol/saml"/>
  </md:IDPSSODescriptor>
</md:EntityDescriptor>

Keycloak uses the realm key to sign assertions and can export it via the Realm Keys tab in the admin console. Remember: every time you rotate the signing key, the metadata already held by the SP must be updated — otherwise all SPs will fail to verify the signature.

#Endpoints and Signing Configuration

In the Settings tab of the SAML client, you configure the key points that determine how the SP talks to the IdP:

• Valid Redirect URIs — the list of valid ACS URLs; these must exactly match the URL the SP uses to receive the Response.
• Master SAML Processing URL — the default URL for processing SAML requests when the SP doesn't provide a specific URL.
• Force POST Binding — forces all Responses to be sent via HTTP POST, useful when the redirect URL is too short for a large assertion.
• Assertion Signature Algorithm — the options are generally RSA-SHA256; use SHA1 only for truly old SPs.

For encryption, Keycloak supports encrypting assertions with the XML Encryption standard. The SP's public key is taken from metadata, then the assertion is encrypted before being sent. You'll need this when the SP requires encrypted assertions.

#Integration Options with Applications

#NameID and SAML Attributes

#NameID Formats

NameID is the user identity carried by the assertion. Its format options are set through the Name ID Format field on the client:

• email — suitable when email is the primary identity at the SP.
• persistent — an identifier that doesn't change for the user's lifetime, suitable for cross-organization federation.
• transient — a one-time identifier, for sessions that don't need to be linked across visits.
• username — the user name in the Keycloak realm.

Force Name ID Format forces the assertion to always use the selected format, ignoring what the SP requests in the AuthnRequest.

#Attribute Statements and Mappers

Attributes in the assertion are managed via the Mappers tab on the client. Each mapper maps one Keycloak user attribute to a SAML attribute name carried by the assertion:

• Attribute Statement — regular attributes such as email, first name, and last name.
• Custom attributes — additional user attributes you define yourself, for example an employee number.
• Attribute filtering — only the attributes mapped through mappers appear in the assertion; this also keeps the assertion small and doesn't leak unnecessary data.

#Testing the Flow and Troubleshooting

Once the client is configured, test it by browsing the SP application and pressing login. Several points to always check when the flow fails:

• Response status — make sure the StatusCode is Success, not Responder or RequestDenied.
• Issuer — the assertion must name an issuer the SP recognizes.
• Signature — the SP's public key must match the realm's current signing key.
• Audience — the audience value must equal the SP's entity ID.
• NameID format — the format sent must be exactly as agreed.
• System clock — assertions carry NotBefore and NotOnOrAfter; a clock difference makes the assertion rejected, so synchronize NTP.

Realm events in Keycloak can be used to observe the flow: the admin console records logins and failures related to this SAML client.

#Closing

In this episode 13, you turned Keycloak on as a SAML IdP: creating a SAML client, understanding the SSO and SLS endpoints, exporting complete metadata with the signing key, configuring encryption and signature algorithms, choosing the NameID format, mapping attributes through mappers, and knowing the main troubleshooting points.

Key takeaways:

• A client with the saml type makes Keycloak an IdP without changing the same realm used for OIDC.
• Metadata is the integration contract — the realms/demo/protocol/saml/descriptor endpoint contains everything the SP needs.
• Signing and encryption options must be agreed on both ways — enabling encryption unilaterally only adds problems.
• Mappers determine the assertion's content — attributes that aren't mapped never reach the SP.

In the next episode (episode 14), we flip sides: Keycloak is ready as an IdP, now you connect a real SAML service provider — Salesforce, Google Workspace, or a Jira application — including how to test assertions with SAML Tracer and handle typical integration errors.