spring-security-samples/servlet/spring-boot/java/saml2/saml-extension-federation/README.adoc

= SAML 2.0 Login & Logout Federation Sample using SAML Extension URLs

This guide provides instructions on setting up the new Spring Security SAML 2.0 support using the endpoint URLs from the EOLd Spring Security SAML Extension.

It differs from the `custom-urls` sample in that it is configured to have the registration id be the entity id for each asserting party, an important consideration when federating against hundreds of endpoints.
This code uses `RelyingPartyRegistrations#collectionFromMetadata` to demonstrate how to copy this relying party's configuration across several arbitrary asserting party configurations returns from a single endpoint.

See the https://github.com/spring-projects/spring-security/wiki/SAML-2.0-Migration-Guide[SAML 2.0 Migration Guide] for more details about the migration.

== Key Changes

=== URL Forwarding Filter

Instead of customizing the default Spring Security configuration, a new `Filter` has been created named `SamlExtensionUrlForwardingFilter`.
This new filter is responsible to forward from the SAML Extension URLs to the new https://docs.spring.io/spring-security/reference/servlet/saml2/login/overview.html[Spring Security SAML 2.0 support URLs].
Below is a table with the URLs that the Filter listen to (column 1) and forwards to (column 2).


|===
|SAML Extension URLs |Spring Security SAML 2.0 Support URLs |Description

|`/saml/SSO`
|`/login/saml2/sso/one`
|The URL that processes a `<saml2:Response>` from the IdP

|`/saml/login`
|`/saml2/authenticate/one`
|The URL that triggers a SAML 2.0 Login

|`/saml/logout`
|`/logout/saml2/slo`
|The URL that trigger an SP's initiated SAML 2.0 Logout

|`/saml/SingleLogout`
|`/logout/saml2/slo`
|The URL that processes a `<saml2:LogoutRequest>` from the IdP

|`/saml/metadata`
|`/saml2/service-provider-metadata/one`
|The URL that generates the SP metadata
|===

Note that the `SamlExtensionUrlForwardingFilter` has an order of `-102`, this makes it be invoked before the `FilterChainProxy`.

[source,java]
----
@Component
@Order(-102) // To run before FilterChainProxy
public class SamlExtensionUrlForwardingFilter extends OncePerRequestFilter {
	// ...
}
----

=== application.yml

[source%linenums,yml]
----
spring:
  security:
    filter:
      dispatcher-types: async, error, request, forward <1>
    saml2:
      relyingparty:
        registration:
          one:
            singlelogout:
              binding: POST
              url: "{baseUrl}/saml/logout" <2>
              responseUrl: "{baseUrl}/saml/SingleLogout" <3>
            acs:
              location: "{baseUrl}/saml/SSO" <4>
            assertingparty.metadata-uri: https://dev-05937739.okta.com/app/exk598vc9bHhwoTXM5d7/sso/saml/metadata
----

==== `RelyingPartyRegistration` properties

The `RelyingPartyRegistration` properties should also be customized to match the values that were used by the SAML Extension (see <2>, <3> and <4> above).

== Run the Sample

=== Start up the Sample Boot Application
```
 ./gradlew :servlet:spring-boot:java:saml2:saml-extension-federation:bootRun
```

=== Open a Browser

http://localhost:8080/

Select the first IdP listed.
You will be redirect to the Okta SAML 2.0 IDP

=== Type in your credentials

```
User: testuser2@spring.security.saml
Password: 12345678
```