From 53827d47d0802670fd53b665643aef8af4fe7bc8 Mon Sep 17 00:00:00 2001 From: Phillip Webb Date: Fri, 10 Apr 2026 17:09:24 -0700 Subject: [PATCH] Move OAuth2 and SAML 2.0 documentation to a security section Closes gh-50022 --- .../antora/modules/ROOT/pages/redirect.adoc | 42 +- .../reference/pages/security/index.adoc | 7 + .../reference/pages/security/oauth2.adoc | 296 +++++++++++++ .../reference/pages/security/saml2.adoc | 107 +++++ .../reference/pages/web/spring-security.adoc | 400 +----------------- .../reference/partials/nav-reference.adoc | 4 + .../client/MyOAuthClientConfiguration.java | 17 +- .../MySamlRelyingPartyConfiguration.java | 2 +- .../client/MyOAuthClientConfiguration.kt | 2 +- .../MyWebFluxSecurityConfiguration.kt | 2 +- 10 files changed, 452 insertions(+), 427 deletions(-) create mode 100644 documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/index.adoc create mode 100644 documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/oauth2.adoc create mode 100644 documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/saml2.adoc rename documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/{web => }/security/oauth2/client/MyOAuthClientConfiguration.java (80%) rename documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/{web => }/security/saml2/relyingparty/MySamlRelyingPartyConfiguration.java (95%) rename documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/{web => }/security/oauth2/client/MyOAuthClientConfiguration.kt (95%) rename documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/{web => }/security/springwebflux/MyWebFluxSecurityConfiguration.kt (95%) diff --git a/documentation/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc b/documentation/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc index 72414df0faa..a62f294c35a 100644 --- a/documentation/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc +++ b/documentation/spring-boot-docs/src/docs/antora/modules/ROOT/pages/redirect.adoc @@ -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] diff --git a/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/index.adoc b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/index.adoc new file mode 100644 index 00000000000..a4392ce6b72 --- /dev/null +++ b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/index.adoc @@ -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. diff --git a/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/oauth2.adoc b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/oauth2.adoc new file mode 100644 index 00000000000..f57b96a172b --- /dev/null +++ b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/oauth2.adoc @@ -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..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..*` 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` +* 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. + + + diff --git a/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/saml2.adoc b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/saml2.adoc new file mode 100644 index 00000000000..144a1240b9b --- /dev/null +++ b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/security/saml2.adoc @@ -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"] +---- + + + shibboleth-releases + Shibboleth Releases Repository + https://build.shibboleth.net/maven/releases + + false + + + +---- + + +[[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[] diff --git a/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/web/spring-security.adoc b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/web/spring-security.adoc index ccbcc6c6a27..86c46862ea1 100644 --- a/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/web/spring-security.adoc +++ b/documentation/spring-boot-docs/src/docs/antora/modules/reference/pages/web/spring-security.adoc @@ -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..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..*` 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` -* 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"] ----- - - - shibboleth-releases - Shibboleth Releases Repository - https://build.shibboleth.net/maven/releases - - false - - - ----- - - -[[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`". diff --git a/documentation/spring-boot-docs/src/docs/antora/modules/reference/partials/nav-reference.adoc b/documentation/spring-boot-docs/src/docs/antora/modules/reference/partials/nav-reference.adoc index fa7ba15090c..3f1235532fd 100644 --- a/documentation/spring-boot-docs/src/docs/antora/modules/reference/partials/nav-reference.adoc +++ b/documentation/spring-boot-docs/src/docs/antora/modules/reference/partials/nav-reference.adoc @@ -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[] diff --git a/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/web/security/oauth2/client/MyOAuthClientConfiguration.java b/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/security/oauth2/client/MyOAuthClientConfiguration.java similarity index 80% rename from documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/web/security/oauth2/client/MyOAuthClientConfiguration.java rename to documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/security/oauth2/client/MyOAuthClientConfiguration.java index f3e35ff60c5..81aba498b9b 100644 --- a/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/web/security/oauth2/client/MyOAuthClientConfiguration.java +++ b/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/security/oauth2/client/MyOAuthClientConfiguration.java @@ -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(); } diff --git a/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/web/security/saml2/relyingparty/MySamlRelyingPartyConfiguration.java b/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/security/saml2/relyingparty/MySamlRelyingPartyConfiguration.java similarity index 95% rename from documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/web/security/saml2/relyingparty/MySamlRelyingPartyConfiguration.java rename to documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/security/saml2/relyingparty/MySamlRelyingPartyConfiguration.java index 99514c1b389..9928ebdc176 100644 --- a/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/web/security/saml2/relyingparty/MySamlRelyingPartyConfiguration.java +++ b/documentation/spring-boot-docs/src/main/java/org/springframework/boot/docs/security/saml2/relyingparty/MySamlRelyingPartyConfiguration.java @@ -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; diff --git a/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/web/security/oauth2/client/MyOAuthClientConfiguration.kt b/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/security/oauth2/client/MyOAuthClientConfiguration.kt similarity index 95% rename from documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/web/security/oauth2/client/MyOAuthClientConfiguration.kt rename to documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/security/oauth2/client/MyOAuthClientConfiguration.kt index e643c3b0256..4b877afa87c 100644 --- a/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/web/security/oauth2/client/MyOAuthClientConfiguration.kt +++ b/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/security/oauth2/client/MyOAuthClientConfiguration.kt @@ -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 diff --git a/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/web/security/springwebflux/MyWebFluxSecurityConfiguration.kt b/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/security/springwebflux/MyWebFluxSecurityConfiguration.kt similarity index 95% rename from documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/web/security/springwebflux/MyWebFluxSecurityConfiguration.kt rename to documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/security/springwebflux/MyWebFluxSecurityConfiguration.kt index c2390c63b1a..5036ccae239 100644 --- a/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/web/security/springwebflux/MyWebFluxSecurityConfiguration.kt +++ b/documentation/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/security/springwebflux/MyWebFluxSecurityConfiguration.kt @@ -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