Learn Keycloak - SAML 2.0 Fundamentals

#Introduction

In episode 11 you handled the session lifecycle: when the SSO session is created, how idle timeout and max timeout constrain it, and how single logout pulls all sessions at once. Episode 12 opens a new phase with SAML 2.0, the XML-based authentication protocol that has become the de facto standard in enterprise environments. You might ask, why learn a protocol that feels old in the OIDC era? Because tens of thousands of corporate applications — from HR portals and ERP to supply chain applications — only provide SAML integration. This episode plants the foundation so that the integrations in episodes 13 and 14 feel light.

#Why SAML 2.0 Is Still the Enterprise Standard

SAML (Security Assertion Markup Language) 2.0 was standardized by OASIS in 2005 and remains the protocol of choice for federation in the corporate world. Three traits keep it going:

• XML-based — every message (request, response, assertion) is represented as a strict XML document, validatable against the XSD schema and signed with XML Signature.
• Enterprise standard — support exists in nearly all identity products: Active Directory Federation Services, Okta, OneLogin, and of course Keycloak.
• Federation use cases — designed to connect identities across organizations through trust between IdP and SP, without ever sharing credentials.

urn:oasis:names:tc:SAML:2.0:assertion is the official namespace for assertion elements. You will often see strings like this in metadata and request documents — a marker that the document follows SAML 2.0 rather than an earlier version.

#SAML 2.0 vs OIDC

Before diving into the components, it's important to see the comparison map with the OIDC you already master:

The rule of thumb from episode 2 applies: choose OIDC for new applications you build yourself, choose SAML when the application being integrated — usually a vendor product — only supports SAML.

#Core SAML Components

SAML works with two main roles and a number of connecting elements:

• Identity Provider (IdP) — the entity that holds identities and issues assertions. In this series, the IdP is Keycloak.
• Service Provider (SP) — the application that protects its resources by accepting assertions from the IdP.
• Assertion — the statement the IdP issues about a user, used as proof of authentication by the SP.
• Binding — the way SAML messages are transported between parties.
• Profile — the combination of assertion, protocol, and binding that forms a specific scenario, for example the Web Browser SSO Profile.

#Most Commonly Used Bindings

Most modern implementations use a combination: AuthnRequest over HTTP Redirect, Response over HTTP POST.

#Two Flows You Must Understand

#SP-Initiated Flow

The most common flow: the user starts from the application. Here are the steps:

1. The user opens the application (SP) and clicks the login button
2. The SP builds an AuthnRequest and sends it to the IdP via HTTP Redirect
3. The IdP checks the session, asking for credentials if not yet logged in
4. The IdP builds a Response containing an Assertion and signs it
5. The browser sends the Response to the SP's ACS endpoint via HTTP POST
6. The SP validates the signature and builds a local session

In step 2, the SP fills the SAMLRequest parameter in the query string. When the IdP answers, it adds the RelayState parameter to carry state back — make sure you return it as-is.

#IdP-Initiated Flow

The reverse of the flow above: the user opens the IdP portal first, chooses the target application, then the IdP sends an assertion without any AuthnRequest from the SP. Faster for the user, but less secure because the SP never verifies the origin of the request — an assertion can be forced without SP initiative.

#Assertion Creation and Validation

Assertion creation happens at the IdP once the user is proven; validation happens at the SP: checking the signature, validity window, audience, and response status. If any of these fails, the assertion is rejected.

#Assertion Structure

The assertion is the heart of SAML. There are three kinds of statements it can carry:

• Authentication assertion — proof that the user was authenticated, including the time and method of authentication.
• Attribute assertion — user attributes such as email, name, and department.
• Authorization decision statement — a decision on whether a subject is allowed to perform a specific action on a resource.

An example of a simplified Response:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
  <saml:Issuer>https://keycloak.example.com/realms/demo</saml:Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:Assertion>
    <saml:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">budi@example.com</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer"/>
    </saml:Subject>
    <saml:AttributeStatement>
      <saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
        <saml:AttributeValue>budi@example.com</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Some elements you should recognize:

• Issuer — the identity of the assertion creator; SPs usually reject assertions from issuers that are not registered.
• NameID — the user identity as seen by the SP; its format (email, persistent, transient) must match the agreement.
• SubjectConfirmation — the mechanism binding the assertion to the recipient; bearer is the most common for browser flows.
• AttributeStatement — the container for attributes that become the material for mapping on the application side.

#Closing

In this episode 12, you got to know SAML 2.0 as an XML protocol for enterprise SSO: its fundamental differences from OIDC, the IdP, SP, assertion, and binding components; the SP-initiated and IdP-initiated flows; and how to read the assertion structure from issuer to attribute statement.

Key takeaways:

• SAML 2.0 is an XML-based authentication protocol designed for enterprise federation, not a replacement for OAuth 2.0.
• Binding determines transport — HTTP Redirect for requests, HTTP POST for large responses, SOAP for back-channel.
• SP-initiated starts from the application, IdP-initiated starts from the identity provider, with different security trade-offs.
• The assertion is proof of authentication — signature, validity window, and audience are the three things the SP validates.

In the next episode (episode 13), you'll place Keycloak in the SAML IdP role: creating a SAML client, exporting metadata, configuring signing and encryption keys, choosing the NameID format, all the way to preparing the ACS and SLS endpoints.