From 2e6103de1af881c41fe949b1b700fabeb6a19c96 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Thu, 1 May 2025 20:06:30 +0900 Subject: [PATCH 01/10] docs(saml2): clarify that HTTP-Redirect binding is not supported for SAML 2.0 responses Signed-off-by: snowykte0426 --- docs/modules/ROOT/pages/migration-7/index.adoc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/modules/ROOT/pages/migration-7/index.adoc b/docs/modules/ROOT/pages/migration-7/index.adoc index 9cdb6dfda5..58206c8abe 100644 --- a/docs/modules/ROOT/pages/migration-7/index.adoc +++ b/docs/modules/ROOT/pages/migration-7/index.adoc @@ -7,3 +7,12 @@ While Spring Security 7.0 does not have a release date yet, it is important to s This preparation guide is designed to summarize the biggest changes in Spring Security 7.0 and provide steps to prepare for them. It is important to keep your application up to date with the latest Spring Security 6 and Spring Boot 3 releases. + +[WARNING] +==== +Spring Security does not support HTTP-Redirect binding for SAML 2.0 Responses. + +According to the SAML specification, the HTTP-Redirect binding is not permitted for SAML Responses due to URL length and signature limitations. Attempting to use this binding may result in unexpected errors. + +Use HTTP-POST binding instead when configuring your identity provider. +==== From 7465866556b3e27b0c923f6bc7a716f71732ffaa Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Fri, 2 May 2025 09:52:10 +0900 Subject: [PATCH 02/10] docs(saml2): migrate SAML 2.0 Migration Guide from Wiki Fixes: gh-11161 Signed-off-by: snowykte0426 --- .../servlet/saml2/saml2-migration-guide.adoc | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc diff --git a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc new file mode 100644 index 0000000000..d8f63dfaa7 --- /dev/null +++ b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc @@ -0,0 +1,72 @@ +NOTE: This document is a work in progress. Please check back regularly for updates. + +This document contains guidance for moving SAML 2.0 Service Providers from Spring Security SAML Extensions 1.x to Spring Security 5.7.x. Since Spring Security doesn’t provide Identity Provider support, migrating a Spring Security SAML Extensions Identity Provider is out of scope for this document. + +Because the two approaches are as different as they are, this document will tend to cover patterns more than precise search-and-replace steps. + +[[saml2-login-logout]] +== Login & Logout + +=== Changes In Approach + +https://github.com/spring-projects/spring-security[Spring Security] takes a slightly different approach from https://github.com/spring-projects/spring-security-saml[Spring Security SAML Extensions] in a few notable ways. + +==== Simplified Enablement + +Spring Security SAML Extensions support for Service Providers is provided by a series of filters enabled by adding each filter manually in the correct order to various Spring Security filter chains. + +Spring Security’s SAML 2.0 Service Provider support is enabled via the Spring Security `saml2Login` and `saml2Logout` DSL methods. It selects the correct filters to add and puts them in the appropriate places in the filter chain. + +==== Stronger Encapsulation + +Like Spring Security SAML Extensions, Spring Security bases it’s SAML support on OpenSAML. The Extensions project exposes OpenSAML over public interfaces, blurring the lines between the two projects, effectively requiring OpenSAML, and making upgrades to later versions of OpenSAML more complicated. + +Spring Security provides stronger encapsulation. No public interfaces expose OpenSAML components and any class that exposes OpenSAML in its public API is named with an `OpenSaml` prefix for additional clarity. + +==== Out-of-the-box Multitenancy + +Spring Security SAML Extensions offered some lightweight support for declaring more than one Identity Provider and accessing it at login time using the `idp` request parameter. This was limiting as far as changing things at runtime was concerned and also doesn’t allow for a many-to-many relationship between relying and asserting parties. + +Spring Security builds SAML 2.0 multitenancy into its default URLs and basic components in the form of a `RelyingPartyRegistration`. This component acts as a link between a Relying Party’s metadata and an Asserting Party’s metadata, and all pairs are available for lookup in a `RelyingPartyRegistrationRepository`. Each URL represents a unique registration pair to be retrieved. + +Whether it’s AuthnRequests, Responses, LogoutRequests, LogoutResponses, or EntityDescriptors, each filter is based off of `RelyingPartyRegistrationRepository` and so is fundamentally multi-tenant. + +=== Examples Matrix + +Both Spring Security and Spring Security SAML Extensions have examples for how to configure the Service Provider: + +[options="header"] +|=== +| Use case | Spring Security | Spring Security SAML Extension + +| Login & Logout | https://github.com/spring-projects/spring-security-samples/tree/main/servlet/spring-boot/java/saml2/login[Sample] | +https://github.com/jzheaux/spring-security-saml-migrate/tree/main/login-logout[Sample] +| Login using SAML Extension URLs | https://github.com/spring-projects/spring-security-samples/tree/main/servlet/spring-boot/java/saml2/custom-urls[Sample] | - +|=== + +You can also see a showcase example in https://github.com/spring-projects/spring-security-saml/tree/main/sample[Spring Security SAML Extension]'s GitHub project. + + +[NOTE] +==== +Spring Security does not support HTTP-Redirect binding for SAML 2.0 Responses. +According to the SAML specification, the HTTP-Redirect binding is not permitted for SAML Responses due to URL length and signature limitations. Attempting to use this binding may result in unexpected errors. +Use HTTP-POST binding instead when configuring your identity provider. +==== + +[[saml2-metadata]] +== Metadata + +Support for metadata is currently quite simple. Additions to its functionality are under consideration. + +`RelyingPartyRegistrations` builds off of the existing multitenancy support and can derive multiple ``RelyingPartyRegistration``s from a single EntityDescriptor endpoint. These can then be paired with locally-configured relying party information as needed. + +For applications that require Spring Security SAML Extension’s refreshable metadata feature, please see https://github.com/spring-projects/spring-security-samples/tree/main/servlet/spring-boot/java/saml2/refreshable-metadata[the associated Spring Security sample] for how to add. + +[[saml2-unported]] +== Unported Features + +There are some features that are not yet ported over and there are as yet no plans to do so: + +* HTTP-Redirect binding for SAML 2.0 Responses +* Artifact binding support From 10b5c052caabbefb612adc82dbe25e11ed3ce0e5 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Fri, 2 May 2025 09:52:21 +0900 Subject: [PATCH 03/10] docs(saml2): add SAML 2.0 Migration Guide to nav.adoc Signed-off-by: snowykte0426 --- docs/modules/ROOT/nav.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index d65fc977c0..c8b504adf6 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -89,6 +89,7 @@ **** xref:servlet/saml2/login/authentication.adoc[SAML2 Authentication Responses] *** xref:servlet/saml2/logout.adoc[SAML2 Logout] *** xref:servlet/saml2/metadata.adoc[SAML2 Metadata] +*** xref:saml2/saml2-migration-guide.adoc[SAML 2.0 Migration Guide] ** xref:servlet/exploits/index.adoc[Protection Against Exploits] *** xref:servlet/exploits/csrf.adoc[] *** xref:servlet/exploits/headers.adoc[] From aa9e8de790b3b35551a8bee2db931465813527a1 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Fri, 2 May 2025 09:52:32 +0900 Subject: [PATCH 04/10] docs(migration): remove redundant SAML HTTP-Redirect warning Signed-off-by: snowykte0426 --- docs/modules/ROOT/pages/migration-7/index.adoc | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/modules/ROOT/pages/migration-7/index.adoc b/docs/modules/ROOT/pages/migration-7/index.adoc index 58206c8abe..9cdb6dfda5 100644 --- a/docs/modules/ROOT/pages/migration-7/index.adoc +++ b/docs/modules/ROOT/pages/migration-7/index.adoc @@ -7,12 +7,3 @@ While Spring Security 7.0 does not have a release date yet, it is important to s This preparation guide is designed to summarize the biggest changes in Spring Security 7.0 and provide steps to prepare for them. It is important to keep your application up to date with the latest Spring Security 6 and Spring Boot 3 releases. - -[WARNING] -==== -Spring Security does not support HTTP-Redirect binding for SAML 2.0 Responses. - -According to the SAML specification, the HTTP-Redirect binding is not permitted for SAML Responses due to URL length and signature limitations. Attempting to use this binding may result in unexpected errors. - -Use HTTP-POST binding instead when configuring your identity provider. -==== From 2fd071c129ed38bdfd4849382fa19fa6f2f7668e Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Wed, 7 May 2025 08:12:27 +0900 Subject: [PATCH 05/10] docs(saml2): remove unnecessary WIP note from migration guide Signed-off-by: snowykte0426 --- .../modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc index d8f63dfaa7..36d169ea7c 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc @@ -1,5 +1,3 @@ -NOTE: This document is a work in progress. Please check back regularly for updates. - This document contains guidance for moving SAML 2.0 Service Providers from Spring Security SAML Extensions 1.x to Spring Security 5.7.x. Since Spring Security doesn’t provide Identity Provider support, migrating a Spring Security SAML Extensions Identity Provider is out of scope for this document. Because the two approaches are as different as they are, this document will tend to cover patterns more than precise search-and-replace steps. From b60b06d0bfcf2b88b11a00dfc4792bc80102e3d8 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Wed, 7 May 2025 08:16:07 +0900 Subject: [PATCH 06/10] docs(saml2): remove version number from Spring Security to ease maintenance Signed-off-by: snowykte0426 --- .../modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc index 36d169ea7c..3f065571cb 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc @@ -1,4 +1,4 @@ -This document contains guidance for moving SAML 2.0 Service Providers from Spring Security SAML Extensions 1.x to Spring Security 5.7.x. Since Spring Security doesn’t provide Identity Provider support, migrating a Spring Security SAML Extensions Identity Provider is out of scope for this document. +This document contains guidance for moving SAML 2.0 Service Providers from Spring Security SAML Extensions 1.x to Spring Security Since Spring Security doesn’t provide Identity Provider support, migrating a Spring Security SAML Extensions Identity Provider is out of scope for this document. Because the two approaches are as different as they are, this document will tend to cover patterns more than precise search-and-replace steps. From 862f7c40d4b44aa6e2468328b9f0662265655a25 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Wed, 7 May 2025 08:21:58 +0900 Subject: [PATCH 07/10] docs(saml2): add xref links for saml2Login, saml2Logout, and saml2Metadata Linked each DSL keyword to its corresponding reference page and updated the wording to present the list clearly. Signed-off-by: snowykte0426 --- .../ROOT/pages/servlet/saml2/saml2-migration-guide.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc index 3f065571cb..d2b4b3b2ec 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc @@ -13,7 +13,10 @@ https://github.com/spring-projects/spring-security[Spring Security] takes a slig Spring Security SAML Extensions support for Service Providers is provided by a series of filters enabled by adding each filter manually in the correct order to various Spring Security filter chains. -Spring Security’s SAML 2.0 Service Provider support is enabled via the Spring Security `saml2Login` and `saml2Logout` DSL methods. It selects the correct filters to add and puts them in the appropriate places in the filter chain. +Spring Security’s SAML 2.0 Service Provider support is enabled via the Spring Security DSL methods: +xref:servlet/saml2/login/index.adoc[`saml2Login`], +xref:servlet/saml2/logout.adoc[`saml2Logout`], and +xref:servlet/saml2/metadata.adoc[`saml2Metadata`]. It selects the correct filters to add and puts them in the appropriate places in the filter chain. ==== Stronger Encapsulation From 4ab9cde0b87284199557b5c7fac5f1ea178007a1 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Wed, 7 May 2025 08:23:52 +0900 Subject: [PATCH 08/10] docs(saml2): remove metadata section and add sample link to examples table Removed the outdated 'Metadata' section per feedback, and moved the sample link into the 'Examples Matrix' table for better visibility and relevance. Signed-off-by: snowykte0426 --- .../pages/servlet/saml2/saml2-migration-guide.adoc | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc index d2b4b3b2ec..c43485ea28 100644 --- a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc +++ b/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc @@ -43,6 +43,7 @@ Both Spring Security and Spring Security SAML Extensions have examples for how t | Login & Logout | https://github.com/spring-projects/spring-security-samples/tree/main/servlet/spring-boot/java/saml2/login[Sample] | https://github.com/jzheaux/spring-security-saml-migrate/tree/main/login-logout[Sample] | Login using SAML Extension URLs | https://github.com/spring-projects/spring-security-samples/tree/main/servlet/spring-boot/java/saml2/custom-urls[Sample] | - +| Metadata support | https://github.com/spring-projects/spring-security-samples/tree/main/servlet/spring-boot/java/saml2/refreshable-metadata[Sample] | - |=== You can also see a showcase example in https://github.com/spring-projects/spring-security-saml/tree/main/sample[Spring Security SAML Extension]'s GitHub project. @@ -55,15 +56,6 @@ According to the SAML specification, the HTTP-Redirect binding is not permitted Use HTTP-POST binding instead when configuring your identity provider. ==== -[[saml2-metadata]] -== Metadata - -Support for metadata is currently quite simple. Additions to its functionality are under consideration. - -`RelyingPartyRegistrations` builds off of the existing multitenancy support and can derive multiple ``RelyingPartyRegistration``s from a single EntityDescriptor endpoint. These can then be paired with locally-configured relying party information as needed. - -For applications that require Spring Security SAML Extension’s refreshable metadata feature, please see https://github.com/spring-projects/spring-security-samples/tree/main/servlet/spring-boot/java/saml2/refreshable-metadata[the associated Spring Security sample] for how to add. - [[saml2-unported]] == Unported Features From 94acb53e5d7e912ee1f0fc879934faff55fa10b8 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Wed, 7 May 2025 08:26:17 +0900 Subject: [PATCH 09/10] docs(saml2): rename migration guide and update navigation entry Renamed 'saml2-migration-guide.adoc' to 'saml-extension-migration.adoc' for clarity, and updated the nav link text to 'Migrating from Spring Security SAML Extension'. Signed-off-by: snowykte0426 --- .../{saml2-migration-guide.adoc => saml-extension-migration.adoc} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/modules/ROOT/pages/servlet/saml2/{saml2-migration-guide.adoc => saml-extension-migration.adoc} (100%) diff --git a/docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc b/docs/modules/ROOT/pages/servlet/saml2/saml-extension-migration.adoc similarity index 100% rename from docs/modules/ROOT/pages/servlet/saml2/saml2-migration-guide.adoc rename to docs/modules/ROOT/pages/servlet/saml2/saml-extension-migration.adoc From 2388710a7a4c8a2b4d79a4acc41a4b6551585ab0 Mon Sep 17 00:00:00 2001 From: snowykte0426 Date: Wed, 7 May 2025 08:26:23 +0900 Subject: [PATCH 10/10] docs(saml2): rename migration guide and update navigation entry Renamed 'saml2-migration-guide.adoc' to 'saml-extension-migration.adoc' for clarity, and updated the nav link text to 'Migrating from Spring Security SAML Extension'. Signed-off-by: snowykte0426 --- docs/modules/ROOT/nav.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index c8b504adf6..cb860d0fb3 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -89,7 +89,7 @@ **** xref:servlet/saml2/login/authentication.adoc[SAML2 Authentication Responses] *** xref:servlet/saml2/logout.adoc[SAML2 Logout] *** xref:servlet/saml2/metadata.adoc[SAML2 Metadata] -*** xref:saml2/saml2-migration-guide.adoc[SAML 2.0 Migration Guide] +*** xref:servlet/saml2/saml-extension-migration.adoc[Migrating from Spring Security SAML Extension] ** xref:servlet/exploits/index.adoc[Protection Against Exploits] *** xref:servlet/exploits/csrf.adoc[] *** xref:servlet/exploits/headers.adoc[]