You must use at least OpenSAML 4.1.1 to update to Spring Security 6's SAML support.
== Use `OpenSaml4AuthenticationProvider`
In order to support both OpenSAML 3 and 4 at the same time, Spring Security released `OpenSamlAuthenticationProvider` and `OpenSaml4AuthenticationProvider`.
In 6.0, because OpenSAML3 support is removed, `OpenSamlAuthenticationProvider` is removed as well.
Not all methods in `OpenSamlAuthenticationProvider` were ported 1-to-1 to `OpenSaml4AuthenticationProvider`.
As such, some adjustment will be required to make the challenge.
Consider the following representative usage of `OpenSamlAuthenticationProvider`:
In an early release of Spring Security's SAML 2.0 support, `Saml2MetadataFilter` and `Saml2AuthenticationTokenConverter` shipped with constructors of type `Converter`.
This level of abstraction made it tricky to evolve the class and so a dedicated interface `RelyingPartyRegistrationResolver` was introduced in a later release.
In 6.0, the `Converter` constructors are removed.
To prepare for this in 5.8, change classes that implement `Converter<HttpServletRequest, RelyingPartyRegistration>` to instead implement `RelyingPartyRegistrationResolver`.
== Change to Using `Saml2AuthenticationRequestResolver`
`Saml2AuthenticationContextResolver` and `Saml2AuthenticationRequestFactory` are removed in 6.0 as is the `Saml2WebSsoAuthenticationRequestFilter` that requires them.
They are replaced by `Saml2AuthenticationRequestResolver` and a new constructor in `Saml2WebSsoAuthenticationRequestFilter`.
The new interface removes an unnecessary transport object between the two classes.
Most applications need do nothing; however, if you use or configure `Saml2AuthenticationRequestContextResolver` or `Saml2AuthenticationRequestFactory`, try the following steps to convert instead use `Saml2AuthenticationRequestResolver`.
=== Use `setAuthnRequestCustomizer` instead of `setAuthenticationRequestContextConverter`
If you are calling `OpenSaml4AuthenticationReqeustFactory#setAuthenticationRequestContextConverter`, for example, like so:
Also, since `setAuthnRequestCustomizer` has direct access to the `HttpServletRequest`, there is no need for a `Saml2AuthenticationRequestContextResolver`.
Simply use `setAuthnRequestCustomizer` to read directly from `HttpServletRequest` this information you need.
=== Use `setAuthnRequestCustomizer` instead of `setProtocolBinding`
Since Spring Security only supports the `POST` binding for authentication, there is not very much value in overriding the protocol binding at this point in time.
====
== Use the latest `Saml2AuthenticationToken` constructor
In an early release, `Saml2AuthenticationToken` took several individual settings as constructor parameters.
This created a challenge each time a new parameter needed to be added.
Since most of these settings were part of `RelyingPartyRegistration`, a new constructor was added where a `RelyingPartyRegistration` could be provided, making the constructor more stable.
It also is valuable in that it more closely aligns with the design of `OAuth2LoginAuthenticationToken`.
Most applications do not construct this class directly since `Saml2WebSsoAuthenticationFilter` does.
However, in the event that your application constructs one, please change from:
In an early release of Spring Security's SAML support, there was some ambiguity on the meaning of certain `RelyingPartyRegistration` methods and their function.
As more capabilities were added to `RelyingPartyRegistration`, it became necessary to clarify this ambiguity by changing method names to ones that aligned with spec language.
The deprecated methods in `RelyingPartyRegstration` are removed.
To prepare for that, consider the following representative usage of `RelyingPartyRegistration`:
For a complete listing of all changed methods, please see {security-api-url}org/springframework/security/saml2/provider/service/registration/RelyingPartyRegistration.html[``RelyingPartyRegistration``'s JavaDoc].
