SAML 2.0

What is SAML 2.0?

SAML 2.0 is a standard for exchanging authentication and authorization data between domains. It enables Single Sign-On (SSO) across different services and applications, allowing users to authenticate once and access multiple resources without re-entering their credentials. SAML 2.0 is widely used in enterprise environments, cloud services, and federated identity systems to establish trust between identity providers and service providers.

SAML uses XML-based messages to communicate authentication and authorization information between the identity provider (IdP) and the service provider (SP). The protocol specifications are defined by the OASIS Security Services Technical Committee, ensuring interoperability and security across different implementations, and it consists in a series of PDF documents that defines the protocol:

• Core specification: Defines the basic concepts and elements of SAML.
• Bindings: Describes how SAML assertions and protocols are mapped to standard messaging or communication protocols.
• Profiles: Defines specific use cases and requirements for SAML implementations.
• Metadata: Specifies the metadata format for SAML entities.
• Conformance: Outlines the requirements for SAML 2.0 conformance.

Having the specifications in PDF formats means that it is not always easy to find the appropriate information in multiple PDF files. A list of all the main specification PDFs can be found in this index page and here.

How does SAML 2.0 work?

Stablishing Trust between Identity Provider and Service Provider

Both the identity provider (IdP) and the service provider (SP) must establish trust before exchanging authentication and authorization data. This trust is established through metadata exchange. SAML Metadata which contains information about the IdP and SP, such as X.509 certificates, endpoints, and supported protocols. The metadata is exchanged between the IdP and SP, allowing them to verify each other’s identity and capabilities.

When configuring SAML 2.0, the IdP and SP typically exchange metadata files that contain information about each other. The metadata will contain the necessary information about the identity provider and service provider, such as:

• EntityID: A unique identifier for the IdP or SP.
• Endpoints: URLs for different services, such as authentication and logout.
• Public keys: Used for signing and encrypting messages.
• Supported protocols: Describes the SAML profiles and bindings supported by the entity.
• Certificates: Public keys used for verifying signatures and encrypting data. Typically, X.509 certificates are used.
• etc…

SAML Request (AuthnRequest)

An AuthnRequest is an XML message sent by a service provider (SP) to an identity provider (IdP) to initiate the authentication process. This message indicates that a user is attempting to access a protected resource and needs to be authenticated by the IdP. The AuthnRequest typically includes information such as a unique identifier for the request, the SP’s EntityID, and the URL where the response should be sent.

In practice, many major IdPs might not use all the information in the AuthnRequest. For example, the URL indicating where to send the response is also present in the SP metadata, and IdPs often trust this metadata information over what is included in the AuthnRequest.

Upon receiving the AuthnRequest, the IdP processes it, authenticates the user, and then sends a corresponding AuthnResponse back to the SP, containing the user’s authentication status and additional assertions.

Signing & Encrypting the AuthnRequest

An AuthnRequest can be signed to ensure its integrity and authenticity. Signing an AuthnRequest verifies that the request has not been altered and confirms that it originates from a trusted service provider (SP). While signing the AuthnRequest is not mandatory, it is recommended for added security, especially in environments where the authenticity of the request is critical.

Encryption of the AuthnRequest, on the other hand, is generally not required, as the primary concern is verifying the integrity and origin of the request rather than protecting its contents. However, organizations may choose to encrypt certain parts of the request if they contain sensitive information.

The IdP metadata will specify if it requires incoming AuthnRequests to be signed with the AuthnRequestsSigned attribute, indicating that the IdP expects to receive signed requests from the SP. However, in practice, many IdPs might not verify the signature and may ignore it if present.

SAML Response (AuthnResponse)

A SAML response (a.k.a Assertion) typically has the following structure:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" ID="_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6" Version="2.0" IssueInstant="2014-07-17T01:01:48Z" Destination="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685">
  <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
  </samlp:Status>
  <saml:Assertion xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" ID="pfx5b5bc3b8-dce4-f605-86f1-f88704eb042f" Version="2.0" IssueInstant="2014-07-17T01:01:48Z">
    <saml:Issuer>http://idp.example.com/metadata.php</saml:Issuer><ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
  <ds:SignedInfo><ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
    <ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
  <ds:Reference URI="#pfx5b5bc3b8-dce4-f605-86f1-f88704eb042f"><ds:Transforms><ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/><ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/></ds:Transforms><ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><ds:DigestValue>v/A4t0oSYaSODgvkCxa4D1ySvrA=</ds:DigestValue></ds:Reference></ds:SignedInfo><ds:SignatureValue>wNsIj3In+ZlNSyWZztwE80r+hyF7ADNOoOlGvyy1KgCGFnFUJE9uD7BLi1LHl5+LAnik4eqWIgfhr9IV5cIghg5MgKxG0I0QG8zZBxoow3PXkeXL60z1j6DDg0sHdLnhOlzKmK6DVWBvI54y5r6qXLhjh90zydNiTFEf31kK4pw=</ds:SignatureValue>
<ds:KeyInfo><ds:X509Data><ds:X509Certificate>MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czETMBEGA1UECAwKQ2FsaWZvcm5pYTEVMBMGA1UECgwMT25lbG9naW4gSW5jMRcwFQYDVQQDDA5zcC5leGFtcGxlLmNvbTAeFw0xNDA3MTcxNDEyNTZaFw0xNTA3MTcxNDEyNTZaMFIxCzAJBgNVBAYTAnVzMRMwEQYDVQQIDApDYWxpZm9ybmlhMRUwEwYDVQQKDAxPbmVsb2dpbiBJbmMxFzAVBgNVBAMMDnNwLmV4YW1wbGUuY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDZx+ON4IUoIWxgukTb1tOiX3bMYzYQiwWPUNMp+Fq82xoNogso2bykZG0yiJm5o8zv/sd6pGouayMgkx/2FSOdc36T0jGbCHuRSbtia0PEzNIRtmViMrt3AeoWBidRXmZsxCNLwgIV6dn2WpuE5Az0bHgpZnQxTKFek0BMKU/d8wIDAQABo1AwTjAdBgNVHQ4EFgQUGHxYqZYyX7cTxKVODVgZwSTdCnwwHwYDVR0jBBgwFoAUGHxYqZYyX7cTxKVODVgZwSTdCnwwDAYDVR0TBAUwAwEB/zANBgkqhkiG9w0BAQ0FAAOBgQByFOl+hMFICbd3DJfnp2Rgd/dqttsZG/tyhILWvErbio/DEe98mXpowhTkC04ENprOyXi7ZbUqiicF89uAGyt1oqgTUCD1VsLahqIcmrzgumNyTwLGWo17WDAa1/usDhetWAMhgzF/Cnf5ek0nK00m0YZGyc4LzgD0CROMASTWNg==</ds:X509Certificate></ds:X509Data></ds:KeyInfo></ds:Signature>
    <saml:Subject>
      <saml:NameID SPNameQualifier="http://sp.example.com/demo1/metadata.php" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">_ce3d2948b4cf20146dee0a0b3dd6f69b6cf86f62d7</saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData NotOnOrAfter="2024-01-18T06:21:48Z" Recipient="http://sp.example.com/demo1/index.php?acs" InResponseTo="ONELOGIN_4fee3b046395c4e751011e97f8900b5273d56685"/>
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotBefore="2014-07-17T01:01:18Z" NotOnOrAfter="2024-01-18T06:21:48Z">
      <saml:AudienceRestriction>
        <saml:Audience>http://sp.example.com/demo1/metadata.php</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement AuthnInstant="2014-07-17T01:01:48Z" SessionNotOnOrAfter="2024-07-17T09:01:48Z" SessionIndex="_be9967abd904ddcae3c0eb4189adbe3f71e327cf93">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:Password</saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute Name="uid" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="mail" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">test@example.com</saml:AttributeValue>
      </saml:Attribute>
      <saml:Attribute Name="eduPersonAffiliation" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
        <saml:AttributeValue xsi:type="xs:string">users</saml:AttributeValue>
        <saml:AttributeValue xsi:type="xs:string">examplerole1</saml:AttributeValue>
      </saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

At a high level, the <Response> element contains important inner elements:

graph TD
    subgraph Response
        Issuer
        Status
        Assertion
    end

• Issuer: This is the EntityID of the IdP that issued the response.
• Status: The status of the response, indicating success or failure.
• Assertion: Contains the actual authentication statement, attributes, and conditions. This is a very important part of the response, as it contains the information about the user’s authentication status and attributes, as well as the conditions under which the assertion is valid (e.g. expiration of the response).

The assertion is particularly important and contains several key elements:

graph TD
    subgraph Response
        Issuer
        Status
        subgraph Assertion
            AssertionIssuer[Issuer]
            Signature
            Subject
            Conditions
            AuthnStatement[AuthnStatement]
            AttributeStatement[AttributeStatement]
        end
    end

Signing & Encrypting the AuthnResponse

Signing the SAML responses is crucial to ensure the integrity and authenticity of the communication between the identity provider (IdP) and the service provider (SP). The signature provides assurance that the response has not been altered in transit and that it indeed originates from the trusted IdP. Typically, the response itself, the assertion, or both can be signed. Signing the response ensures the overall security of the entire message, while signing the assertion specifically secures the attributes and authentication statements contained within.

Creating a signature for a SAML response involves the IdP using its private key to generate a digital signature:

• First, the IdP creates a hash of the response or assertion using a hashing algorithm, transforming the data into a fixed-size string of characters.
• Next, the hash is encrypted with the IdP’s private key to create the digital signature. This signature is then appended to the SAML response or assertion.

To verify the signature, the SP uses the IdP’s public key (from the X.509 contained in the Metadata). The SP verifies the signature using this public key. If both hashes match, the SP can confirm the integrity and authenticity of the SAML response or assertion, verifying that it was indeed sent by the trusted IdP and has not been tampered with.

Authentication Flows

SAML 2.0 supports two authentication flows: SP-initiated and IdP-initiated.

SP-Initiated Flow

In the SP-initiated flow, the user attempts to access a service provided by the SP. The following steps outline the SP-initiated flow:

sequenceDiagram
    participant User
    participant SP as Service Provider
    participant IDP as Identity Provider
    
    User->>SP: Request access to resource
    SP->>User: Generate SAML Request with RelayState, redirect to IDP
    User->>IDP: Forward SAML Request
    IDP->>IDP: Verify SAML Request
    IDP->>User: Authenticate and generate SAML Response with RelayState
    User->>SP: Forward SAML Response
    SP->>SP: Verify SAML Response
    SP->>User: Grant access to resource

1. User requests access to a resource on the SP.
2. SP generates a SAML authentication request (AuthnRequest) and includes a RelayState for maintaining application state. The SP redirects the user’s browser to the IDP with the SAML request.
3. IDP receives the AuthnRequest and verifies its authenticity and integrity. This typically involves checking the request’s signature and ensuring it’s from a trusted SP.
4. IDP authenticates the user. This step may involve presenting a login form where the user enters credentials.
5. IDP generates a SAML response (Assertion) indicating the authentication result. This response includes an assertion about the user’s identity and possibly attributes.
6. IDP includes the original RelayState in the response to preserve application state.
7. SP receives the SAML Response and verifies its authenticity and integrity. This involves checking the response’s signature and ensuring it’s from a trusted IDP.
8. SP grants access to the user based on the SAML Assertion. The SP may initiate a session for the user.

IdP-Initiated Flow

In the IdP-initiated flow, the user is authenticated by the IdP and then redirected to the SP. The following steps outline the IdP-initiated flow:

sequenceDiagram
    participant User
    participant IDP as Identity Provider
    participant SP as Service Provider

    User->>IDP: Access IDP portal and authenticate
    IDP->>User: User selects SP
    IDP->>User: Generate SAML Response with RelayState for SP
    User->>SP: Forward SAML Response
    SP->>SP: Verify SAML Response
    SP->>User: Grant access to resource

1. User accesses IDP portal and is authenticated.
2. User selects a service (SP) from the IDP portal.
3. IDP generates a SAML Response (Assertion) for the selected SP. This response is unsolicited, meaning it was not preceded by an AuthnRequest from the SP.
4. The SAML Response includes an assertion about the user’s identity and possibly attributes. The IDP also includes a RelayState if necessary to maintain application state.
5. SP receives the SAML Response and verifies its authenticity and integrity. The SP ensures the response is from a trusted IDP and checks the signature.
6. SP grants access to the user based on the SAML Assertion. The SP may initiate a session for the user.

Useful tools and resources

• SAML Tool: SAML Tool: An online tool for encoding and decoding SAML messages.
• SAML Tracer - Firefox Extension: SAML Tracer: A Firefox add-on for viewing and debugging SAML messages.
• SAML Tracer - Chrome Extension: SAML Chrome Extension: A Chrome extension for viewing and debugging SAML messages.
• SAML Schema Navigation: SAML Schema Navigation: A list of SAML schema elements and their definitions.

SAML 2.0 vs. OIDC

SAML 2.0 and OpenID Connect (OIDC) are both protocols used for authentication and authorization, but they have different use cases and design philosophies.