SSOGEN / Learn / Spring Boot SAML 2.0 SSO
Learn
Spring Boot SAML 2.0 SSO
Spring Boot SAML login is built into Spring Security: add one dependency, point it at the identity provider's metadata and call saml2Login(). This page shows which setting is copied from the IdP and which goes back to it.

Spring Security includes SAML 2.0 service provider login, so a Spring Boot application needs the spring-security-saml2-service-provider dependency, the identity provider’s metadata address and saml2Login(). The IdP supplies its entity ID, sign-in URL and certificate. Your application gives back its own entity ID and ACS URL.
That makes it a two-way copy between two files, and every login failure is a mismatch in that copy. The background is in what SAML is. If you first saw the “Please sign in” form, the Spring Security default login page explains it. This page follows the current references, Spring Boot 4.1 and Spring Security 7.1, read on 2026-11-17. The setting names and URL patterns below are the same in Spring Boot 3.5 and Spring Security 6.5.
Each setting is copied from the metadata or sent back to it
The IdP columns use SSOGEN’s documented example host, sso.acme.example, which is fictional. The application is app.acme.example and the registration ID is acme, a name you choose.
<EntityDescriptor entityID="https://sso.acme.example/saml/idp"> <!-- 1 --> <IDPSSODescriptor ...> <KeyDescriptor use="signing"> ... <ds:X509Certificate> MIIC... <!-- 3 --> </ds:X509Certificate> </KeyDescriptor> <SingleSignOnService ... Location="https://sso.acme.example/saml/idp/sso"/> <!-- 2 --> </IDPSSODescriptor></EntityDescriptor># under spring.security.saml2.relyingparty.registration.acmeassertingparty: entity-id: https://sso.acme.example/saml/idp # 1 singlesignon: url: https://sso.acme.example/saml/idp/sso # 2 verification: credentials: - certificate-location: classpath:idp.crt # 3 # metadata-uri: https://sso.acme.example/saml/idp/metadata # 4: one line instead of 1 to 3The numbers match the rows of the table. Each IdP value is copied once, and a mismatch in any of them fails the login.
| Setting | IdP side | Spring Boot side |
|---|---|---|
| 1. IdP entity ID | https://sso.acme.example/saml/idp |
assertingparty.entity-id |
| 2. IdP sign-in URL | https://sso.acme.example/saml/idp/sso |
assertingparty.singlesignon.url |
| 3. IdP signing certificate | The certificate in the metadata | assertingparty.verification.credentials[0].certificate-location |
| 4. Rows 1 to 3 together | https://sso.acme.example/saml/idp/metadata |
assertingparty.metadata-uri |
| 5. Your entity ID | The IdP’s “SP entity ID” field | Default {baseUrl}/saml2/service-provider-metadata/{registrationId} |
| 6. Your ACS URL | The IdP’s “ACS URL” field | Default {baseUrl}/login/saml2/sso/{registrationId} |
Rows 1 to 4 flow from the IdP into your application.yml. Rows 5 and 6 flow the other way: Spring generates them, and the IdP administrator must hold the same strings. ACS URL, entity ID and audience explains why each is matched exactly.
Add SAML login in three steps
- Add the dependency. SAML support builds on OpenSAML, so the Shibboleth repository is needed as well.
<repositories> <repository> <id>shibboleth-releases</id> <url>https://build.shibboleth.net/maven/releases/</url> </repository></repositories><dependencies> <dependency> <groupId>org.springframework.security</groupId> <artifactId>spring-security-saml2-service-provider</artifactId> </dependency></dependencies>- Register the identity provider. One line reads the whole IdP file. Spring Boot takes
acmeas the registration ID.
spring: security: saml2: relyingparty: registration: acme: assertingparty: metadata-uri: https://sso.acme.example/saml/idp/metadata- Enable the login and the metadata endpoint. Spring Boot’s default chain calls only
saml2Login(), so addsaml2Metadata()to publish your side.
@Configuration@EnableWebSecuritypublic class SecurityConfig { @Bean SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authorize -> authorize.anyRequest().authenticated()) .saml2Login(Customizer.withDefaults()) .saml2Metadata(Customizer.withDefaults()); return http.build(); }}To type rows 1 to 3 by hand, use entity-id, singlesignon.url and verification.credentials under assertingparty instead of metadata-uri. Set singlesignon.sign-request: false when the IdP does not require signed requests.
What you send to the IdP
Spring publishes your entity ID and ACS URL as SAML metadata at {baseUrl}/saml2/metadata/{registrationId}. For this example, that is https://app.acme.example/saml2/metadata/acme.
- Entity ID.
https://app.acme.example/saml2/service-provider-metadata/acme. Paste it into the IdP’s SP entity ID field. Spring also checks that the assertion’s audience equals it. - ACS URL.
https://app.acme.example/login/saml2/sso/acme. Spring checks the assertion’s recipient against it. - Metadata URL. The address above, or the downloaded XML. It saves typing rows 5 and 6.
- What comes back. Spring uses the assertion’s NameID as the principal name, so ask for the identifier your user table holds, usually the email address.
Single logout is a separate set of URLs. See SAML single logout before you promise it.
Four errors cover most failed first logins
Spring checks the response in a fixed order: signature, issuer and destination, assertion signature, then timestamps, subject and audience. The first failure stops the login. The error codes and the “Invalid assertion” prefix below are from the Spring Security 7.1.2 source.
| What you see | Cause | Field to check | Fix |
|---|---|---|---|
invalid_signature |
No signature on the response or on any assertion, or the certificate Spring holds does not verify it | Certificate in verification.credentials or the metadata |
Import the IdP’s current signing certificate again, for example after it rotates |
invalid_assertion, audience |
The assertion’s audience is not your entity ID | Row 5: the IdP’s SP entity ID against Spring’s | Make the strings identical, or set entity-id on the registration; check scheme, host and port behind a proxy |
invalid_assertion, “not yet valid” or expired |
The assertion’s NotBefore or NotOnOrAfter falls outside your clock plus tolerance |
Clocks on both servers | Synchronise both clocks first, then set clockSkew only for the small remainder |
invalid_destination or invalid_issuer |
The Destination is not the URL that received the POST, or the Issuer is not the configured IdP entity ID | Rows 6 and 1 | Copy the ACS URL and IdP entity ID again, character for character |
Spring prefixes an assertion failure with “Invalid assertion [id] for SAML response [id]:” and then the reason. To read the message the IdP actually sent, capture the login in the SAML Tracer. The SAML assertion page names each field you will see.
OpenSAML does the XML work, and Tomcat is only the container
- OpenSAML. Spring Security’s SAML 2.0 support is built on the OpenSAML library. The 7.1 reference names
OpenSaml5AuthenticationProvideras the default. In 6.5 the default isOpenSaml4AuthenticationProvider, and the OpenSAML 5 provider is an option. - Tomcat.
saml2Login()belongs to Spring Security, so only an application that uses it has the SAML login. A Tomcat application without Spring Security needs another route: OpenID Connect, or the Java agent in the next section. - OpenID Connect. If the IdP offers it, Spring Boot with OAuth2 and OIDC is the shorter configuration.
Without writing the SAML code
SSOGEN is a SAML IdP, and its Java agent protects a Java application with no code change. They solve different halves of the same job.
Before: SAML in your application. You maintain the dependency, the registration, the IdP certificate copy and the entity ID and ACS match, and you diagnose the four errors above each time something is renamed or rotated.
After: the SSOGEN Java agent. It adds single sign-on and multi-factor authentication to a Tomcat 9, 10.1 or 11 application, or a Spring Boot 3.5 application, with no change to the code. You paste one settings file that carries the agent key. On Spring Boot you set ssogen.agent.config-file; on Tomcat you add the agent’s valve. The Spring Boot starter needs Java 17 or later.
The Java agent guide has the steps, and the Java agent page lists what it covers.
When your application must act as a SAML service provider, the SAML IdP page covers SSOGEN’s side. SSOGEN reads SP metadata from an https URL or an uploaded XML file, and shows the IdP metadata address, entity ID, sign-in URL and signing certificate on the application’s Integration tab.
SSOGEN’s Test step previews the assertion’s NameID, audience, recipient and attributes before anyone signs in.
Questions people ask
What is the default ACS URL in Spring Security SAML2?
It is {baseUrl}/login/saml2/sso/{registrationId}. For registration acme on https://app.acme.example, that is https://app.acme.example/login/saml2/sso/acme. Spring maps it to the filter that accepts the POSTed SAMLResponse. Give the IdP this exact URL, or override it with acs.location in Spring Boot or assertionConsumerServiceLocation in Java.
How do I get the SP metadata to send to the IdP?
Enable saml2Metadata(), then open /saml2/metadata/{registrationId}. Spring also answers on /saml2/metadata and /saml2/service-provider-metadata/{registrationId}. Download the XML or give the IdP administrator the URL. It carries the entity ID and ACS URL that rows 5 and 6 in the table above describe.
How much clock skew does Spring Security allow?
The OpenSaml5AuthenticationProvider.AssertionValidator builder documents a default of 5 minutes. Change it with AssertionValidator.builder().clockSkew(Duration.ofMinutes(10)).build(), which the 7.1 reference shows with 10 minutes. Treat a larger value as a workaround, because the better fix is synchronised clocks.
Check it before you ship
Open your metadata in the SAML metadata checker, capture one real login and compare each value with the six rows above. More guides are on the Learn hub.
Sources, all read 2026-11-17:
- Spring Security 7.1, SAML 2.0 Login Overview, Authenticating Responses, SAML 2.0 Metadata, Spring Boot 4.1, SAML 2.0, Saml2RelyingPartyProperties in Spring Boot 4.1.2, Saml2ErrorCodes and OpenSaml5AuthenticationProvider in Spring Security 7.1.2, and for the 6.5 and 3.5 comparison the 6.5 overview and Spring Boot 3.5.0 properties
Updated