Key points

• Mostly used as a web-based authentication mechanism because it relies on using the browser agent to broker the authentication flow.

• The SP never directly interacts with the IdP. A browser acts as the agent to carry out all the redirects.

• The SP needs to know which IdP to redirect to before it has any idea who the user is.

• The SP doesn't know who the user is until the SAML assertion comes back from the IdP.

• This flow doesn't have to start from the SP. An IdP can initiate an authentication flow.

• The SAML authentication flow is asynchronous. The SP doesn't know if the IdP ever completes the entire flow. Because of this, the SP doesn't maintain any state of authentication requests generated. When the SP receives a response from an IdP, the response must contain all the necessary information.

Workflow

SAML 2.0

SAML Authority

SAML Identity Provider

e.g. Microsoft Entra ID

• Issues SAML assertions

• Defined by IDPSSODescriptor in metadata schema

• Requires

  • SP's sign-in endpoint to which SAML responses are posted

SAML Relying Party / SAML Service Provider

• Receive SAML assertions from SAML Identity Provider

• Defined by SPSSODescriptor in metadata schema

• The SP needs to obtain the public certificate from the IdP to validate the signature. The certificate is stored on the SP side and used whenever a SAML response arrives.

• Requires

  • IdP's public certificate for signature validation
  • IdP's sign-in endpoint to which SAML requests are posted

Message Bindings

Different ways to send SAML messages between SP and IdP.

• HTTP Redirect

  SAML protocol messages can be carried directly in the URL query string of an HTTP GET request. Since the length of URLs is limited in practice, the HTTP Redirect binding is suitable for short messages, such as the <samlp:AuthnRequest> message, and unsuitable for long messages, such as the SAML response message.

  The value of the SAMLRequest parameter is the base64-encoding of a <samlp:AuthnRequest> element, which is transmitted to the IdP via the browser.

• HTTP POST

  Usually for sending SAML response

• HTTP Artifact

  A SAML message is transmitted from one entity to another either by value or by reference. A reference to a SAML message is called an artifact.

  

  • Improving SAML SSO Security Using HTTP Artifact Binding (opens in a new tab)

• Resources

  • Using HTTP POST binding in OpenSAML 4 | SAMLSecurity (opens in a new tab)

Example

IdP (Microsoft Entra ID)

• Azure console

  • Home

    • Enterprise applications

      • <The application you have created>

        • Manage

          • Single sign-on

• Basic SAML Configuration (for SP)

  Microsoft Entra ID	Spring Security SAML2	Example value	Notes
  Identifier (Entity ID)	Saml2RelyingPartyProperties.Registration.entityId	microsoft_entra_saml_toolkit	SP's SAML2 Entity ID, must be unique across all applications in your Microsoft Entra tenant. The default identifier will be the audience of the SAML response for IdP-initiated SSO.
  Reply URL (Assertion Consumer Service URL)	Saml2RelyingPartyProperties.Registration.acs	http://localhost:8444/SAML/Consume	SP's ACS endpoint, where the application expects to receive the authentication token, aka Assertion Consumer Service (ACS) in SAML.
  Sign on URL		https://samltoolkit.azurewebsites.net/saml/login	SP's sign-in page URL for SP-initiated SSO, unnecessary if you want to perform IdP-initiated SSO.
  Relay State (Optional)		<Optional>	SP's endpoint for a successful authentication, to which users are redirected after authentication is completed, and the value is typically a URL or URL path that takes users to a specific location within the application.
  Logout URL (Optional)		<Optional>	SP's endpoint for a successful logout, to which the SAML logout response (saml2p:LogoutResponse) is sent.

SP (Spring Security - SAML2)

• org.springframework.security.config.annotation.web.configurers.saml2.Saml2LoginConfigurer

• org.springframework.boot.autoconfigure.security.saml2.Saml2RelyingPartyProperties

  SAML2 relying party properties

• org.springframework.boot.autoconfigure.security.saml2.Saml2RelyingPartyRegistrationConfiguration

  @Configuration used to map Saml2RelyingPartyProperties to relying party registrations in a RelyingPartyRegistrationRepository.

• org.springframework.security.saml2.provider.service.web.Saml2WebSsoAuthenticationRequestFilter

• application.yaml

  spring:
    security:
      saml2:
        relyingparty:
          registration:
            app-name:
              entity-id: "microsoft_entra_saml_toolkit" # SP's SAML2 Entity ID
              singlelogout:
                binding: POST # Whether to redirect or post logout requests.
                url: "{baseUrl}/saml/logout" # Location where SAML2 LogoutRequest gets sent to
                responseUrl: "{baseUrl}/saml/SingleLogout" # Location where SAML2 LogoutResponse gets sent to, Microsoft Entra ID (Basic SAML Configuration - Logout Url (Optional))
              acs:
                location: "{baseUrl}/saml/consume" # Microsoft Entra ID (Basic SAML Configuration - Reply URL (Assertion Consumer Service URL))
              assertingparty: # IdP details (In this case, Microsoft Entra ID), if metadata URL is used, no need to configure other properties
                metadata-uri: https://login.microsoftonline.com/4e85adc7-d172-460b-8494-c13fe4e9e43e/federationmetadata/2007-06/federationmetadata.xml?appid=81e5c415-19cf-45fe-b923-9e99f7955f82 # Microsoft Entra ID (SAML Certificates - App Federation Metadata Url)

• Filters

  Name	Notes	Type
  Saml2WebSsoAuthenticationRequestFilter	Formulates a SAML 2.0 AuthnRequest	org.springframework.security.saml2.provider.service.web.Saml2WebSsoAuthenticationRequestFilter
  Saml2WebSsoAuthenticationFilter	Attempts to perform authentication from SAML 2.0 Response; Use AuthenticationConverter to convert SAML 2.0 Response to Authentication token	org.springframework.security.saml2.provider.service.web.authentication.Saml2WebSsoAuthenticationFilter

Tools

• SAML DEVELOPER TOOLS (opens in a new tab)
• Mock SAML - A free SAML 2.0 Identity Provider for testing SAML SSO integrations. (opens in a new tab)

Troubleshooting

Signature Validation Error

This could be caused by spaces in the certificate Base64-encoded string. Use a one-line string to represent the certificate.

Resources

• Reference

  • Spring Security - SAML2 (opens in a new tab)
  • Understanding SAML | Okta Developer (opens in a new tab)
  • Wikipedia - SAML 2.0 (opens in a new tab)
  • Security Assertion Markup Language (SAML) V2.0 Technical Overview (opens in a new tab)

• Troubleshooting

  • K51854802: Decoding SAML Requests for troubleshooting SAML Authentication (opens in a new tab)