Move OAuth2 and SAML 2.0 documentation to a security section

Closes gh-50022
This commit is contained in:
Phillip Webb
2026-04-10 21:09:58 -07:00
parent a0c27bb4f1
commit 53827d47d0
10 changed files with 452 additions and 427 deletions
@@ -1843,6 +1843,27 @@
* xref:reference:packaging/native-image/introducing-graalvm-native-images.adoc#packaging.native-image.introducing-graalvm-native-images.understanding-aot-processing.source-code-generation[#packaging.native-image.introducing-graalvm-native-images.understanding-aot-processing.source-code-generation]
* xref:reference:packaging/native-image/introducing-graalvm-native-images.adoc#packaging.native-image.introducing-graalvm-native-images.understanding-aot-processing[#packaging.native-image.introducing-graalvm-native-images.understanding-aot-processing]
* xref:reference:packaging/native-image/introducing-graalvm-native-images.adoc#packaging.native-image.introducing-graalvm-native-images[#native-image.introducing-graalvm-native-images]
* xref:reference:security/oauth2.adoc#security.oauth2.authorization-server[#boot-features-security-authorization-server]
* xref:reference:security/oauth2.adoc#security.oauth2.authorization-server[#features.security.authorization-server]
* xref:reference:security/oauth2.adoc#security.oauth2.authorization-server[#web.security.oauth2.authorization-server]
* xref:reference:security/oauth2.adoc#security.oauth2.client.common-providers[#boot-features-security-oauth2-common-providers]
* xref:reference:security/oauth2.adoc#security.oauth2.client.common-providers[#features.security.oauth2.client.common-providers]
* xref:reference:security/oauth2.adoc#security.oauth2.client.common-providers[#web.security.oauth2.client.common-providers]
* xref:reference:security/oauth2.adoc#security.oauth2.client[#boot-features-security-oauth2-client]
* xref:reference:security/oauth2.adoc#security.oauth2.client[#features.security.oauth2.client]
* xref:reference:security/oauth2.adoc#security.oauth2.client[#web.security.oauth2.client]
* xref:reference:security/oauth2.adoc#security.oauth2.server[#boot-features-security-oauth2-server]
* xref:reference:security/oauth2.adoc#security.oauth2.server[#features.security.oauth2.server]
* xref:reference:security/oauth2.adoc#security.oauth2.server[#web.security.oauth2.server]
* xref:reference:security/oauth2.adoc#security.oauth2[#boot-features-security-oauth2]
* xref:reference:security/oauth2.adoc#security.oauth2[#features.security.oauth2]
* xref:reference:security/oauth2.adoc#security.oauth2[#web.security.oauth2]
* xref:reference:security/saml2.adoc#security.saml2.relying-party[#boot-features-security-saml2-relying-party]
* xref:reference:security/saml2.adoc#security.saml2.relying-party[#features.security.saml2.relying-party]
* xref:reference:security/saml2.adoc#security.saml2.relying-party[#web.security.saml2.relying-party]
* xref:reference:security/saml2.adoc#security.saml2[#boot-features-security-saml]
* xref:reference:security/saml2.adoc#security.saml2[#features.security.saml2]
* xref:reference:security/saml2.adoc#security.saml2[#web.security.saml2]
* xref:reference:testing/index.adoc#testing[#boot-features-testing]
* xref:reference:testing/index.adoc#testing[#features.testing]
* xref:reference:testing/spring-applications.adoc#testing.spring-applications[#boot-features-testing-spring-applications]
@@ -2166,27 +2187,6 @@
* xref:reference:web/spring-hateoas.adoc#web.spring-hateoas[#boot-features-spring-hateoas]
* xref:reference:web/spring-hateoas.adoc#web.spring-hateoas[#features.spring-hateoas]
* xref:reference:web/spring-hateoas.adoc#web.spring-hateoas[#web.spring-hateoas]
* xref:reference:web/spring-security.adoc#web.security.oauth2.authorization-server[#boot-features-security-authorization-server]
* xref:reference:web/spring-security.adoc#web.security.oauth2.authorization-server[#features.security.authorization-server]
* xref:reference:web/spring-security.adoc#web.security.oauth2.authorization-server[#web.security.oauth2.authorization-server]
* xref:reference:web/spring-security.adoc#web.security.oauth2.client.common-providers[#boot-features-security-oauth2-common-providers]
* xref:reference:web/spring-security.adoc#web.security.oauth2.client.common-providers[#features.security.oauth2.client.common-providers]
* xref:reference:web/spring-security.adoc#web.security.oauth2.client.common-providers[#web.security.oauth2.client.common-providers]
* xref:reference:web/spring-security.adoc#web.security.oauth2.client[#boot-features-security-oauth2-client]
* xref:reference:web/spring-security.adoc#web.security.oauth2.client[#features.security.oauth2.client]
* xref:reference:web/spring-security.adoc#web.security.oauth2.client[#web.security.oauth2.client]
* xref:reference:web/spring-security.adoc#web.security.oauth2.server[#boot-features-security-oauth2-server]
* xref:reference:web/spring-security.adoc#web.security.oauth2.server[#features.security.oauth2.server]
* xref:reference:web/spring-security.adoc#web.security.oauth2.server[#web.security.oauth2.server]
* xref:reference:web/spring-security.adoc#web.security.oauth2[#boot-features-security-oauth2]
* xref:reference:web/spring-security.adoc#web.security.oauth2[#features.security.oauth2]
* xref:reference:web/spring-security.adoc#web.security.oauth2[#web.security.oauth2]
* xref:reference:web/spring-security.adoc#web.security.saml2.relying-party[#boot-features-security-saml2-relying-party]
* xref:reference:web/spring-security.adoc#web.security.saml2.relying-party[#features.security.saml2.relying-party]
* xref:reference:web/spring-security.adoc#web.security.saml2.relying-party[#web.security.saml2.relying-party]
* xref:reference:web/spring-security.adoc#web.security.saml2[#boot-features-security-saml]
* xref:reference:web/spring-security.adoc#web.security.saml2[#features.security.saml2]
* xref:reference:web/spring-security.adoc#web.security.saml2[#web.security.saml2]
* xref:reference:web/spring-security.adoc#web.security.spring-mvc[#boot-features-security-mvc]
* xref:reference:web/spring-security.adoc#web.security.spring-mvc[#features.security.spring-mvc]
* xref:reference:web/spring-security.adoc#web.security.spring-mvc[#web.security.spring-mvc]
@@ -0,0 +1,7 @@
[[security]]
= Security
Spring Boot provides helpful support for general purpose security features such as OAuth2 and SAML 2.0.
This section covers those general purpose security concerns.
If you're looking to secure web applications, see the xref:web/spring-security.adoc#web.security[web security section] instead of this one.
@@ -0,0 +1,296 @@
[[security.oauth2]]
= OAuth2
https://oauth.net/2/[OAuth2] is a widely used authorization framework.
[[security.oauth2.client]]
== Client
If you have `spring-security-oauth2-client` on your classpath, you can take advantage of some auto-configuration to set up OAuth2/Open ID Connect clients.
This configuration makes use of the properties under javadoc:org.springframework.boot.security.oauth2.client.autoconfigure.OAuth2ClientProperties[].
The same properties are applicable to both servlet and reactive web applications.
Each registration must specify an OAuth 2 provider.
When set, the value of the `spring.security.oauth2.client.registration.<registration-id>.provider` property is used to specify the registration's provider.
If the `provider` property is not set, the registration's ID is used instead.
Both approaches are shown in the following example:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
registration:
my-client:
client-id: "abcd"
client-secret: "password"
provider: "example"
example:
client-id: "abcd"
client-secret: "password"
----
The registrations `my-client` and `example` will both use the provider with ID `example`.
The former will do so due to the value of the `spring.security.oauth2.client.registration.my-client.provider` property.
The latter will do so due to its ID being `example` and there being no `provider` property configured for the registration.
The specified provider can either be a reference to a provider configured using `spring.security.oauth2.client.provider.<provider-id>.*` properties or one of the xref:security/oauth2.adoc#security.oauth2.client.common-providers[known common providers].
You can register multiple OAuth2 clients and providers under the `spring.security.oauth2.client` prefix, as shown in the following example:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
registration:
my-login-client:
client-id: "abcd"
client-secret: "password"
client-name: "Client for OpenID Connect"
provider: "my-oauth-provider"
scope: "openid,profile,email,phone,address"
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
client-authentication-method: "client_secret_basic"
authorization-grant-type: "authorization_code"
my-client-1:
client-id: "abcd"
client-secret: "password"
client-name: "Client for user scope"
provider: "my-oauth-provider"
scope: "user"
redirect-uri: "{baseUrl}/authorized/user"
client-authentication-method: "client_secret_basic"
authorization-grant-type: "authorization_code"
my-client-2:
client-id: "abcd"
client-secret: "password"
client-name: "Client for email scope"
provider: "my-oauth-provider"
scope: "email"
redirect-uri: "{baseUrl}/authorized/email"
client-authentication-method: "client_secret_basic"
authorization-grant-type: "authorization_code"
provider:
my-oauth-provider:
authorization-uri: "https://my-auth-server.com/oauth2/authorize"
token-uri: "https://my-auth-server.com/oauth2/token"
user-info-uri: "https://my-auth-server.com/userinfo"
user-info-authentication-method: "header"
jwk-set-uri: "https://my-auth-server.com/oauth2/jwks"
user-name-attribute: "name"
----
In this example, there are three registrations.
In order of declaration, their IDs are `my-login-client`, `my-client-1`, and `my-client-2`.
There is also a single provider with ID `my-oauth-provider`.
For OpenID Connect providers that support https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect discovery], the configuration can be further simplified.
The provider needs to be configured with an `issuer-uri` which is the URI that it asserts as its Issuer Identifier.
For example, if the `issuer-uri` provided is `+https://example.com+`, then an "`OpenID Provider Configuration Request`" will be made to `+https://example.com/.well-known/openid-configuration+`.
The result is expected to be an "`OpenID Provider Configuration Response`".
The following example shows how an OpenID Connect Provider can be configured with the `issuer-uri`:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
provider:
oidc-provider:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
----
By default, Spring Security's javadoc:org.springframework.security.oauth2.client.web.OAuth2LoginAuthenticationFilter[] only processes URLs matching `/login/oauth2/code/*`.
If you want to customize the `redirect-uri` to use a different pattern, you need to provide configuration to process that custom pattern.
For example, for servlet applications, you can add your own javadoc:org.springframework.security.web.SecurityFilterChain[] that resembles the following:
include-code::MyOAuthClientConfiguration[]
TIP: Spring Boot auto-configures an javadoc:org.springframework.security.oauth2.client.InMemoryOAuth2AuthorizedClientService[] which is used by Spring Security for the management of client registrations.
The javadoc:org.springframework.security.oauth2.client.InMemoryOAuth2AuthorizedClientService[] has limited capabilities and we recommend using it only for development environments.
For production environments, consider using a javadoc:org.springframework.security.oauth2.client.JdbcOAuth2AuthorizedClientService[] or creating your own implementation of javadoc:org.springframework.security.oauth2.client.OAuth2AuthorizedClientService[].
[[security.oauth2.client.common-providers]]
=== OAuth2 Client Registration for Common Providers
For common OAuth2 and OpenID providers (Google, Github, Facebook, and Okta), we provide a set of provider defaults.
The IDs of these common provides are `google`, `github`, `facebook`, and `okta`, respectively.
If you do not need to customize these providers, set the registration's `provider` property to the ID of one of the common providers.
Alternatively, you can xref:security/oauth2.adoc#security.oauth2.client[use a registration ID that matches the ID of the provider].
The two configurations in the following example use the common `google` provider:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
registration:
my-client:
client-id: "abcd"
client-secret: "password"
provider: "google"
google:
client-id: "abcd"
client-secret: "password"
----
[[security.oauth2.server]]
== Resource Server
If you have `spring-security-oauth2-resource-server` on your classpath, Spring Boot can set up an OAuth2 Resource Server.
For JWT configuration, a JWK Set URI or OIDC Issuer URI needs to be specified, as shown in the following examples:
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
----
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
----
NOTE: If the authorization server does not support a JWK Set URI, you can configure the resource server with the Public Key used for verifying the signature of the JWT.
This can be done using the configprop:spring.security.oauth2.resourceserver.jwt.public-key-location[] property, where the value needs to point to a file containing the public key in the PEM-encoded x509 format.
The configprop:spring.security.oauth2.resourceserver.jwt.audiences[] property can be used to specify the expected values of the aud claim in JWTs.
For example, to require JWTs to contain an aud claim with the value `my-audience`:
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
jwt:
audiences:
- "my-audience"
----
The same properties are applicable for both servlet and reactive applications.
Alternatively, you can define your own javadoc:org.springframework.security.oauth2.jwt.JwtDecoder[] bean for servlet applications or a javadoc:org.springframework.security.oauth2.jwt.ReactiveJwtDecoder[] for reactive applications.
In cases where opaque tokens are used instead of JWTs, you can configure the following properties to validate tokens through introspection:
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
opaquetoken:
introspection-uri: "https://example.com/check-token"
client-id: "my-client-id"
client-secret: "my-client-secret"
----
Again, the same properties are applicable for both servlet and reactive applications.
The result is an auto-configured introspector. Either a javadoc:org.springframework.security.oauth2.server.resource.introspection.SpringOpaqueTokenIntrospector[] or, in a reactive application, a javadoc:org.springframework.security.oauth2.server.resource.introspection.SpringReactiveOpaqueTokenIntrospector[].
These auto-configured introspectors can be customized using javadoc:org.springframework.boot.security.oauth2.server.resource.autoconfigure.SpringOpaqueTokenIntrospectorBuilderCustomizer[] and javadoc:org.springframework.boot.security.oauth2.server.resource.autoconfigure.reactive.SpringReactiveOpaqueTokenIntrospectorBuilderCustomizer[] beans respectively.
To take complete control of the introspection, define your own javadoc:org.springframework.security.oauth2.server.resource.introspection.OpaqueTokenIntrospector[] or javadoc:org.springframework.security.oauth2.server.resource.introspection.ReactiveOpaqueTokenIntrospector[] bean.
[[security.oauth2.authorization-server]]
== Authorization Server
If you have `spring-security-oauth2-authorization-server` on your classpath, you can take advantage of some auto-configuration to set up a Servlet-based OAuth2 Authorization Server.
You can register multiple OAuth2 clients under the `spring.security.oauth2.authorizationserver.client` prefix, as shown in the following example:
[configprops,yaml]
----
spring:
security:
oauth2:
authorizationserver:
client:
my-client-1:
registration:
client-id: "abcd"
client-secret: "{noop}secret1"
client-authentication-methods:
- "client_secret_basic"
authorization-grant-types:
- "authorization_code"
- "refresh_token"
redirect-uris:
- "https://my-client-1.com/login/oauth2/code/abcd"
- "https://my-client-1.com/authorized"
scopes:
- "openid"
- "profile"
- "email"
- "phone"
- "address"
require-authorization-consent: true
token:
authorization-code-time-to-live: 5m
access-token-time-to-live: 10m
access-token-format: "reference"
reuse-refresh-tokens: false
refresh-token-time-to-live: 30m
my-client-2:
registration:
client-id: "efgh"
client-secret: "{noop}secret2"
client-authentication-methods:
- "client_secret_jwt"
authorization-grant-types:
- "client_credentials"
scopes:
- "user.read"
- "user.write"
jwk-set-uri: "https://my-client-2.com/jwks"
token-endpoint-authentication-signing-algorithm: "RS256"
----
NOTE: The `client-secret` property must be in a format that can be matched by the configured javadoc:org.springframework.security.crypto.password.PasswordEncoder[].
The default instance of javadoc:org.springframework.security.crypto.password.PasswordEncoder[] is created via `PasswordEncoderFactories.createDelegatingPasswordEncoder()`.
The auto-configuration Spring Boot provides for Spring Authorization Server is designed for getting started quickly.
Most applications will require customization and will want to define several beans to override auto-configuration.
The following components can be defined as beans to override auto-configuration specific to Spring Authorization Server:
* javadoc:org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository[]
* javadoc:org.springframework.security.oauth2.server.authorization.settings.AuthorizationServerSettings[]
* javadoc:org.springframework.security.web.SecurityFilterChain[]
* `com.nimbusds.jose.jwk.source.JWKSource<com.nimbusds.jose.proc.SecurityContext>`
* javadoc:org.springframework.security.oauth2.jwt.JwtDecoder[]
TIP: Spring Boot auto-configures an javadoc:org.springframework.security.oauth2.server.authorization.client.InMemoryRegisteredClientRepository[] which is used by Spring Authorization Server for the management of registered clients.
The javadoc:org.springframework.security.oauth2.server.authorization.client.InMemoryRegisteredClientRepository[] has limited capabilities and we recommend using it only for development environments.
For production environments, consider using a javadoc:org.springframework.security.oauth2.server.authorization.client.JdbcRegisteredClientRepository[] or creating your own implementation of javadoc:org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository[].
Additional information can be found in the {url-spring-security-docs}/servlet/oauth2/authorization-server/getting-started.html[Getting Started] chapter of Spring Security Reference Documentation.
@@ -0,0 +1,107 @@
[[security.saml2]]
= SAML 2.0
https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html[SAML v2.0] is a widely adopted framework for exchanging security information between online business partners.
[[security.saml2.build]]
== Build Configuration
SAML 2.0 support builds off of the OpenSAML library that https://shibboleth.atlassian.net/wiki/spaces/DEV/pages/1123844333/Use+of+Maven+Central#Publishing-to-Maven-Central[requires an extra repository] configuration.
[[security.saml2.build.maven]]
=== Using Maven
With Maven, you need to add an extra `repository` element to your POM as follows:
[source,xml,subs="verbatim,attributes"]
----
<repositories>
<repository>
<id>shibboleth-releases</id>
<name>Shibboleth Releases Repository</name>
<url>https://build.shibboleth.net/maven/releases</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
----
[[security.saml2.build.gradle]]
=== Using Gradle
With Gradle, a repository element should be added to your build script:
[source,gradle,subs="verbatim,attributes"]
----
repositories {
maven { url "https://build.shibboleth.net/maven/releases" }
}
----
[[security.saml2.relying-party]]
== Relying Party
If you have `spring-security-saml2-service-provider` on your classpath, you can take advantage of some auto-configuration to set up a SAML 2.0 Relying Party.
This configuration makes use of the properties under javadoc:org.springframework.boot.security.saml2.autoconfigure.Saml2RelyingPartyProperties[].
A relying party registration represents a paired configuration between an Identity Provider, IDP, and a Service Provider, SP.
You can register multiple relying parties under the `spring.security.saml2.relyingparty` prefix, as shown in the following example:
[configprops,yaml]
----
spring:
security:
saml2:
relyingparty:
registration:
my-relying-party1:
signing:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
decryption:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
singlelogout:
url: "https://myapp/logout/saml2/slo"
response-url: "https://remoteidp2.slo.url"
binding: "POST"
assertingparty:
verification:
credentials:
- certificate-location: "path-to-verification-cert"
entity-id: "remote-idp-entity-id1"
sso-url: "https://remoteidp1.sso.url"
my-relying-party2:
signing:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
decryption:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
assertingparty:
verification:
credentials:
- certificate-location: "path-to-other-verification-cert"
entity-id: "remote-idp-entity-id2"
sso-url: "https://remoteidp2.sso.url"
singlelogout:
url: "https://remoteidp2.slo.url"
response-url: "https://myapp/logout/saml2/slo"
binding: "POST"
----
For SAML2 logout, by default, Spring Security's javadoc:org.springframework.security.saml2.provider.service.web.authentication.logout.Saml2LogoutRequestFilter[] and javadoc:org.springframework.security.saml2.provider.service.web.authentication.logout.Saml2LogoutResponseFilter[] only process URLs matching `/logout/saml2/slo`.
If you want to customize the `url` to which AP-initiated logout requests get sent to or the `response-url` to which an AP sends logout responses to, to use a different pattern, you need to provide configuration to process that custom pattern.
For example, for servlet applications, you can add your own javadoc:org.springframework.security.web.SecurityFilterChain[] that resembles the following:
include-code::MySamlRelyingPartyConfiguration[]
@@ -88,403 +88,15 @@ include-code::MyWebFluxSecurityConfiguration[]
[[web.security.oauth2]]
== OAuth2
== [[web.security.oauth2.client]][[web.security.oauth2.client.common-providers]][[web.security.oauth2.server]][[web.security.oauth2.authorization-server]]OAuth2
https://oauth.net/2/[OAuth2] is a widely used authorization framework that is supported by Spring.
[[web.security.oauth2.client]]
=== Client
If you have `spring-security-oauth2-client` on your classpath, you can take advantage of some auto-configuration to set up OAuth2/Open ID Connect clients.
This configuration makes use of the properties under javadoc:org.springframework.boot.security.oauth2.client.autoconfigure.OAuth2ClientProperties[].
The same properties are applicable to both servlet and reactive applications.
Each registration must specify an OAuth 2 provider.
When set, the value of the `spring.security.oauth2.client.registration.<registration-id>.provider` property is used to specify the registration's provider.
If the `provider` property is not set, the registration's ID is used instead.
Both approaches are shown in the following example:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
registration:
my-client:
client-id: "abcd"
client-secret: "password"
provider: "example"
example:
client-id: "abcd"
client-secret: "password"
----
The registrations `my-client` and `example` will both use the provider with ID `example`.
The former will do so due to the value of the `spring.security.oauth2.client.registration.my-client.provider` property.
The latter will do so due to its ID being `example` and there being no `provider` property configured for the registration.
The specified provider can either be a reference to a provider configured using `spring.security.oauth2.client.provider.<provider-id>.*` properties or one of the xref:web/spring-security.adoc#web.security.oauth2.client.common-providers[known common providers].
You can register multiple OAuth2 clients and providers under the `spring.security.oauth2.client` prefix, as shown in the following example:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
registration:
my-login-client:
client-id: "abcd"
client-secret: "password"
client-name: "Client for OpenID Connect"
provider: "my-oauth-provider"
scope: "openid,profile,email,phone,address"
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
client-authentication-method: "client_secret_basic"
authorization-grant-type: "authorization_code"
my-client-1:
client-id: "abcd"
client-secret: "password"
client-name: "Client for user scope"
provider: "my-oauth-provider"
scope: "user"
redirect-uri: "{baseUrl}/authorized/user"
client-authentication-method: "client_secret_basic"
authorization-grant-type: "authorization_code"
my-client-2:
client-id: "abcd"
client-secret: "password"
client-name: "Client for email scope"
provider: "my-oauth-provider"
scope: "email"
redirect-uri: "{baseUrl}/authorized/email"
client-authentication-method: "client_secret_basic"
authorization-grant-type: "authorization_code"
provider:
my-oauth-provider:
authorization-uri: "https://my-auth-server.com/oauth2/authorize"
token-uri: "https://my-auth-server.com/oauth2/token"
user-info-uri: "https://my-auth-server.com/userinfo"
user-info-authentication-method: "header"
jwk-set-uri: "https://my-auth-server.com/oauth2/jwks"
user-name-attribute: "name"
----
In this example, there are three registrations.
In order of declaration, their IDs are `my-login-client`, `my-client-1`, and `my-client-2`.
There is also a single provider with ID `my-oauth-provider`.
For OpenID Connect providers that support https://openid.net/specs/openid-connect-discovery-1_0.html[OpenID Connect discovery], the configuration can be further simplified.
The provider needs to be configured with an `issuer-uri` which is the URI that it asserts as its Issuer Identifier.
For example, if the `issuer-uri` provided is "https://example.com", then an "OpenID Provider Configuration Request" will be made to "https://example.com/.well-known/openid-configuration".
The result is expected to be an "OpenID Provider Configuration Response".
The following example shows how an OpenID Connect Provider can be configured with the `issuer-uri`:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
provider:
oidc-provider:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
----
By default, Spring Security's javadoc:org.springframework.security.oauth2.client.web.OAuth2LoginAuthenticationFilter[] only processes URLs matching `/login/oauth2/code/*`.
If you want to customize the `redirect-uri` to use a different pattern, you need to provide configuration to process that custom pattern.
For example, for servlet applications, you can add your own javadoc:org.springframework.security.web.SecurityFilterChain[] that resembles the following:
include-code::MyOAuthClientConfiguration[]
TIP: Spring Boot auto-configures an javadoc:org.springframework.security.oauth2.client.InMemoryOAuth2AuthorizedClientService[] which is used by Spring Security for the management of client registrations.
The javadoc:org.springframework.security.oauth2.client.InMemoryOAuth2AuthorizedClientService[] has limited capabilities and we recommend using it only for development environments.
For production environments, consider using a javadoc:org.springframework.security.oauth2.client.JdbcOAuth2AuthorizedClientService[] or creating your own implementation of javadoc:org.springframework.security.oauth2.client.OAuth2AuthorizedClientService[].
[[web.security.oauth2.client.common-providers]]
==== OAuth2 Client Registration for Common Providers
For common OAuth2 and OpenID providers (Google, Github, Facebook, and Okta), we provide a set of provider defaults.
The IDs of these common provides are `google`, `github`, `facebook`, and `okta`, respectively.
If you do not need to customize these providers, set the registration's `provider` property to the ID of one of the common providers.
Alternatively, you can xref:web/spring-security.adoc#web.security.oauth2.client[use a registration ID that matches the ID of the provider].
The two configurations in the following example use the common `google` provider:
[configprops,yaml]
----
spring:
security:
oauth2:
client:
registration:
my-client:
client-id: "abcd"
client-secret: "password"
provider: "google"
google:
client-id: "abcd"
client-secret: "password"
----
[[web.security.oauth2.server]]
=== Resource Server
If you have `spring-security-oauth2-resource-server` on your classpath, Spring Boot can set up an OAuth2 Resource Server.
For JWT configuration, a JWK Set URI or OIDC Issuer URI needs to be specified, as shown in the following examples:
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
----
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
----
NOTE: If the authorization server does not support a JWK Set URI, you can configure the resource server with the Public Key used for verifying the signature of the JWT.
This can be done using the configprop:spring.security.oauth2.resourceserver.jwt.public-key-location[] property, where the value needs to point to a file containing the public key in the PEM-encoded x509 format.
The configprop:spring.security.oauth2.resourceserver.jwt.audiences[] property can be used to specify the expected values of the aud claim in JWTs.
For example, to require JWTs to contain an aud claim with the value `my-audience`:
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
jwt:
audiences:
- "my-audience"
----
The same properties are applicable for both servlet and reactive applications.
Alternatively, you can define your own javadoc:org.springframework.security.oauth2.jwt.JwtDecoder[] bean for servlet applications or a javadoc:org.springframework.security.oauth2.jwt.ReactiveJwtDecoder[] for reactive applications.
In cases where opaque tokens are used instead of JWTs, you can configure the following properties to validate tokens through introspection:
[configprops,yaml]
----
spring:
security:
oauth2:
resourceserver:
opaquetoken:
introspection-uri: "https://example.com/check-token"
client-id: "my-client-id"
client-secret: "my-client-secret"
----
Again, the same properties are applicable for both servlet and reactive applications.
The result is an auto-configured introspector. Either a javadoc:org.springframework.security.oauth2.server.resource.introspection.SpringOpaqueTokenIntrospector[] or, in a reactive application, a javadoc:org.springframework.security.oauth2.server.resource.introspection.SpringReactiveOpaqueTokenIntrospector[].
These auto-configured introspectors can be customized using javadoc:org.springframework.boot.security.oauth2.server.resource.autoconfigure.SpringOpaqueTokenIntrospectorBuilderCustomizer[] and javadoc:org.springframework.boot.security.oauth2.server.resource.autoconfigure.reactive.SpringReactiveOpaqueTokenIntrospectorBuilderCustomizer[] beans respectively.
To take complete control of the introspection, define your own javadoc:org.springframework.security.oauth2.server.resource.introspection.OpaqueTokenIntrospector[] or javadoc:org.springframework.security.oauth2.server.resource.introspection.ReactiveOpaqueTokenIntrospector[] bean.
[[web.security.oauth2.authorization-server]]
=== Authorization Server
If you have `spring-security-oauth2-authorization-server` on your classpath, you can take advantage of some auto-configuration to set up a Servlet-based OAuth2 Authorization Server.
You can register multiple OAuth2 clients under the `spring.security.oauth2.authorizationserver.client` prefix, as shown in the following example:
[configprops,yaml]
----
spring:
security:
oauth2:
authorizationserver:
client:
my-client-1:
registration:
client-id: "abcd"
client-secret: "{noop}secret1"
client-authentication-methods:
- "client_secret_basic"
authorization-grant-types:
- "authorization_code"
- "refresh_token"
redirect-uris:
- "https://my-client-1.com/login/oauth2/code/abcd"
- "https://my-client-1.com/authorized"
scopes:
- "openid"
- "profile"
- "email"
- "phone"
- "address"
require-authorization-consent: true
token:
authorization-code-time-to-live: 5m
access-token-time-to-live: 10m
access-token-format: "reference"
reuse-refresh-tokens: false
refresh-token-time-to-live: 30m
my-client-2:
registration:
client-id: "efgh"
client-secret: "{noop}secret2"
client-authentication-methods:
- "client_secret_jwt"
authorization-grant-types:
- "client_credentials"
scopes:
- "user.read"
- "user.write"
jwk-set-uri: "https://my-client-2.com/jwks"
token-endpoint-authentication-signing-algorithm: "RS256"
----
NOTE: The `client-secret` property must be in a format that can be matched by the configured javadoc:org.springframework.security.crypto.password.PasswordEncoder[].
The default instance of javadoc:org.springframework.security.crypto.password.PasswordEncoder[] is created via `PasswordEncoderFactories.createDelegatingPasswordEncoder()`.
The auto-configuration Spring Boot provides for Spring Authorization Server is designed for getting started quickly.
Most applications will require customization and will want to define several beans to override auto-configuration.
The following components can be defined as beans to override auto-configuration specific to Spring Authorization Server:
* javadoc:org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository[]
* javadoc:org.springframework.security.oauth2.server.authorization.settings.AuthorizationServerSettings[]
* javadoc:org.springframework.security.web.SecurityFilterChain[]
* `com.nimbusds.jose.jwk.source.JWKSource<com.nimbusds.jose.proc.SecurityContext>`
* javadoc:org.springframework.security.oauth2.jwt.JwtDecoder[]
TIP: Spring Boot auto-configures an javadoc:org.springframework.security.oauth2.server.authorization.client.InMemoryRegisteredClientRepository[] which is used by Spring Authorization Server for the management of registered clients.
The javadoc:org.springframework.security.oauth2.server.authorization.client.InMemoryRegisteredClientRepository[] has limited capabilities and we recommend using it only for development environments.
For production environments, consider using a javadoc:org.springframework.security.oauth2.server.authorization.client.JdbcRegisteredClientRepository[] or creating your own implementation of javadoc:org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository[].
Additional information can be found in the {url-spring-security-docs}/servlet/oauth2/authorization-server/getting-started.html[Getting Started] chapter of Spring Security Reference Documentation.
https://oauth.net/2/[OAuth2] is a widely used authorization framework.
For details of how to configure and use OAuth2 with your web applications, see the xref:security/oauth2.adoc#security.oauth2["`OAuth2`" section] of under "`Security`".
[[web.security.saml2]]
== SAML 2.0
== [[web.security.saml2.build]][[web.security.saml2.build.maven]][[web.security.saml2.build.gradle]][[web.security.saml2.relying-party]]SAML 2.0
[[web.security.saml2.build]]
=== Build Configuration
SAML 2.0 support builds off of the OpenSAML library that https://shibboleth.atlassian.net/wiki/spaces/DEV/pages/1123844333/Use+of+Maven+Central#Publishing-to-Maven-Central[requires an extra repository] configuration.
[[web.security.saml2.build.maven]]
==== Using Maven
With Maven, you need to add an extra `repository` element to your POM as follows:
[source,xml,subs="verbatim,attributes"]
----
<repositories>
<repository>
<id>shibboleth-releases</id>
<name>Shibboleth Releases Repository</name>
<url>https://build.shibboleth.net/maven/releases</url>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
----
[[web.security.saml2.build.gradle]]
==== Using Gradle
With Gradle, a repository element should be added to your build script:
[source,gradle,subs="verbatim,attributes"]
----
repositories {
maven { url "https://build.shibboleth.net/maven/releases" }
}
----
[[web.security.saml2.relying-party]]
=== Relying Party
If you have `spring-security-saml2-service-provider` on your classpath, you can take advantage of some auto-configuration to set up a SAML 2.0 Relying Party.
This configuration makes use of the properties under javadoc:org.springframework.boot.security.saml2.autoconfigure.Saml2RelyingPartyProperties[].
A relying party registration represents a paired configuration between an Identity Provider, IDP, and a Service Provider, SP.
You can register multiple relying parties under the `spring.security.saml2.relyingparty` prefix, as shown in the following example:
[configprops,yaml]
----
spring:
security:
saml2:
relyingparty:
registration:
my-relying-party1:
signing:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
decryption:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
singlelogout:
url: "https://myapp/logout/saml2/slo"
response-url: "https://remoteidp2.slo.url"
binding: "POST"
assertingparty:
verification:
credentials:
- certificate-location: "path-to-verification-cert"
entity-id: "remote-idp-entity-id1"
sso-url: "https://remoteidp1.sso.url"
my-relying-party2:
signing:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
decryption:
credentials:
- private-key-location: "path-to-private-key"
certificate-location: "path-to-certificate"
assertingparty:
verification:
credentials:
- certificate-location: "path-to-other-verification-cert"
entity-id: "remote-idp-entity-id2"
sso-url: "https://remoteidp2.sso.url"
singlelogout:
url: "https://remoteidp2.slo.url"
response-url: "https://myapp/logout/saml2/slo"
binding: "POST"
----
For SAML2 logout, by default, Spring Security's javadoc:org.springframework.security.saml2.provider.service.web.authentication.logout.Saml2LogoutRequestFilter[] and javadoc:org.springframework.security.saml2.provider.service.web.authentication.logout.Saml2LogoutResponseFilter[] only process URLs matching `/logout/saml2/slo`.
If you want to customize the `url` to which AP-initiated logout requests get sent to or the `response-url` to which an AP sends logout responses to, to use a different pattern, you need to provide configuration to process that custom pattern.
For example, for servlet applications, you can add your own javadoc:org.springframework.security.web.SecurityFilterChain[] that resembles the following:
include-code::MySamlRelyingPartyConfiguration[]
https://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html[SAML v2.0] is a widely adopted framework for exchanging security information between online business partners.
For details of how to configure and use SAML 2.0 with your web applications, see the xref:security/saml2.adoc#security.saml2["`SAML 2.0`" section] under "`Security`".
@@ -57,6 +57,10 @@
*** xref:reference:messaging/spring-integration.adoc[]
*** xref:reference:messaging/websockets.adoc[]
** xref:reference:security/index.adoc[]
*** xref:reference:security/oauth2.adoc[]
*** xref:reference:security/saml2.adoc[]
** xref:reference:testing/index.adoc[]
*** xref:reference:testing/test-modules.adoc[]
*** xref:reference:testing/test-scope-dependencies.adoc[]
@@ -14,7 +14,7 @@
* limitations under the License.
*/
package org.springframework.boot.docs.web.security.oauth2.client;
package org.springframework.boot.docs.security.oauth2.client;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@@ -29,15 +29,14 @@ public class MyOAuthClientConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) {
// @formatter:off
http
.authorizeHttpRequests((requests) -> requests
.anyRequest().authenticated()
http.authorizeHttpRequests((requests) ->
requests.anyRequest().authenticated()
);
http.oauth2Login((login) ->
login.redirectionEndpoint((endpoint) ->
endpoint.baseUri("/login/oauth2/callback/*")
)
.oauth2Login((login) -> login
.redirectionEndpoint((endpoint) -> endpoint
.baseUri("/login/oauth2/callback/*")
)
);
);
// @formatter:on
return http.build();
}
@@ -14,7 +14,7 @@
* limitations under the License.
*/
package org.springframework.boot.docs.web.security.saml2.relyingparty;
package org.springframework.boot.docs.security.saml2.relyingparty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
@@ -14,7 +14,7 @@
* limitations under the License.
*/
package org.springframework.boot.docs.web.security.oauth2.client
package org.springframework.boot.docs.security.oauth2.client
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
@@ -14,7 +14,7 @@
* limitations under the License.
*/
package org.springframework.boot.docs.web.security.springwebflux
package org.springframework.boot.docs.security.springwebflux
import org.springframework.boot.security.autoconfigure.web.reactive.PathRequest
import org.springframework.context.annotation.Bean