Learn Keycloak - SAML Service Provider Integration

#Introduction

In episode 13 you turned Keycloak on as a SAML IdP: creating a SAML client, exporting metadata, and configuring signing keys. Episode 14 completes it from the other side: the service provider. You'll connect real applications — Salesforce, Google Workspace, AWS, down to Jira and Confluence — by exchanging metadata, matching entity IDs and ACS URLs, mapping NameID and attributes, then testing assertions and fixing the errors that appear most often.

#Popular SPs in the Field

One enjoyable thing about SAML: nearly every enterprise product provides an option to integrate with an external identity provider. The ones most frequently encountered:

• Salesforce — configures SSO through the Setup menu with SAML Single Sign-On Settings and requires a unique entity ID and ACS URL.
• Google Workspace — can be pointed at a custom IdP as a third-party SSO provider.
• AWS — via the IAM identity provider that connects Keycloak as a federation source.
• Office 365 / Azure AD — supports SAML for applications that need federation with corporate identity systems.
• Jira / Confluence — Atlassian products provide SAML SSO on enterprise and data center plans.

#Metadata Exchange

The foundation of every SAML integration is a two-way metadata exchange:

1. IdP metadata to SP — you take Keycloak's metadata from realms/demo/protocol/saml/descriptor and register it in the application.
2. SP metadata to IdP — you take the SP's metadata from the application and import it into Keycloak as a SAML client.

With both metadata exchanged, both parties automatically know the other's endpoints, keys, and bindings. An SP metadata snippet looks roughly like this:

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     entityID="https://jira.example.com">
  <md:SPSSODescriptor AuthnRequestsSigned="true"
                      protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                 Location="https://jira.example.com/plugins/servlet/saml/consumer"
                                 index="0" isDefault="true"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

From this metadata, Keycloak can directly infer the SP's entity ID, ACS URL, and binding.

#SP Configuration Elements

When configuring the SP (either in Keycloak or in the application), four elements must match on both sides:

Entity ID is the identity Keycloak uses as the audience value in the assertion. In Keycloak, this is filled in the Client ID field when creating the SAML client. Make sure the value is truly identical to what the SP expects — often a difference of a single letter or a trailing slash is enough to break the integration.

#ACS URL

The Assertion Consumer Service URL is the address in the application that receives the Response from the browser. When creating the client in Keycloak, you put the ACS URL in Valid Redirect URIs. If the SP sends the URL without a trailing slash, you must register both variations so it doesn't fail.

#NameID and Attribute Mapping

Once the SP receives the assertion, the application maps the NameID to its internal account. That's why the NameID format must be consistent — if the SP expects email, the Name ID Format on the Keycloak client must be email, and the assertion must carry an email address matching the account in the application.

The same goes for attributes: SPs like Salesforce often ask for firstName, lastName, and email under specific names. You create a mapper in the Mappers tab of the SAML client for each attribute, then adjust the SAML attribute names to exactly what the SP documents.

#Testing with SAML Tracer

When the integration fails, the first helpful step is to look at the assertion being sent. The most commonly used tools:

• SAML Tracer — a browser extension that displays every SAML message (request and response) along with its XML structure while you walk through the login flow.
• SAML decoder — a tool for decoding encoded SAML documents, whether URL-based or base64.

The recommended testing steps:

1. Enable SAML Tracer in the browser
2. Open the application URL (SP) then click login
3. Follow the redirect flow to the Keycloak login page
4. Log in with a valid user
5. In SAML Tracer, select the last Response request
6. Inspect the status, issuer, audience, NameID, and assertion attributes

Note: the SAMLRequest from the SP appears on the way in, the SAMLResponse from the IdP appears on the way back. Both can be read raw in SAML Tracer.

#Assertion Validation

When inspecting an assertion, the validation order is:

1. The response status must be Success.
2. The signature is valid — the public key matches the IdP's current signing key.
3. The audience contains the SP's entity ID.
4. NameID and attributes match the expected account.
5. The assertion's time is still within NotBefore and NotOnOrAfter.

#Common Errors and Their Fixes

A special note about signatures: after you rotate the signing key in Keycloak, assertions previously signed with the old key will be rejected by the SP. The solution is always the same — import the new IdP metadata into the SP.

#Closing

In this episode 14, you connected real applications as SAML service providers to Keycloak: getting to know popular SPs, exchanging metadata both ways, matching entity ID, ACS URL, NameID, and attributes on both sides, testing the flow with SAML Tracer, and handling typical errors such as invalid signature and audience mismatch.

Key takeaways:

• Two-way metadata is the integration foundation — IdP and SP copy each other's capabilities.
• Entity ID, ACS URL, NameID, and attributes must be identical on both sides — the smallest difference triggers failure.
• SAML Tracer is the primary debugging tool — capture the assertion first, then change configuration.
• Key rotation must be followed by re-importing metadata to all SPs.

In the next episode (episode 15), we shift from authentication to identity storage: user federation — connecting Keycloak to LDAP and Active Directory so users don't have to be duplicated in every system.