294 lines
14 KiB
Plaintext
294 lines
14 KiB
Plaintext
[[web.security]]
|
||
== Spring Security
|
||
If {spring-security}[Spring Security] is on the classpath, then web applications are secured by default.
|
||
Spring Boot relies on Spring Security’s content-negotiation strategy to determine whether to use `httpBasic` or `formLogin`.
|
||
To add method-level security to a web application, you can also add `@EnableGlobalMethodSecurity` with your desired settings.
|
||
Additional information can be found in the {spring-security-docs}/servlet/authorization/method-security.html[Spring Security Reference Guide].
|
||
|
||
The default `UserDetailsService` has a single user.
|
||
The user name is `user`, and the password is random and is printed at WARN level when the application starts, as shown in the following example:
|
||
|
||
[indent=0]
|
||
----
|
||
Using generated security password: 78fa095d-3f4c-48b1-ad50-e24c31d5cf35
|
||
|
||
This generated password is for development use only. Your security configuration must be updated before running your application in production.
|
||
----
|
||
|
||
NOTE: If you fine-tune your logging configuration, ensure that the `org.springframework.boot.autoconfigure.security` category is set to log `WARN`-level messages.
|
||
Otherwise, the default password is not printed.
|
||
|
||
You can change the username and password by providing a `spring.security.user.name` and `spring.security.user.password`.
|
||
|
||
The basic features you get by default in a web application are:
|
||
|
||
* A `UserDetailsService` (or `ReactiveUserDetailsService` in case of a WebFlux application) bean with in-memory store and a single user with a generated password (see {spring-boot-module-api}/autoconfigure/security/SecurityProperties.User.html[`SecurityProperties.User`] for the properties of the user).
|
||
* Form-based login or HTTP Basic security (depending on the `Accept` header in the request) for the entire application (including actuator endpoints if actuator is on the classpath).
|
||
* A `DefaultAuthenticationEventPublisher` for publishing authentication events.
|
||
|
||
You can provide a different `AuthenticationEventPublisher` by adding a bean for it.
|
||
|
||
|
||
|
||
[[web.security.spring-mvc]]
|
||
=== MVC Security
|
||
The default security configuration is implemented in `SecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`.
|
||
`SecurityAutoConfiguration` imports `SpringBootWebSecurityConfiguration` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications.
|
||
To switch off the default web application security configuration completely or to combine multiple Spring Security components such as OAuth2 Client and Resource Server, add a bean of type `SecurityFilterChain` (doing so does not disable the `UserDetailsService` configuration or Actuator's security).
|
||
|
||
To also switch off the `UserDetailsService` configuration, you can add a bean of type `UserDetailsService`, `AuthenticationProvider`, or `AuthenticationManager`.
|
||
|
||
Access rules can be overridden by adding a custom `SecurityFilterChain` or `WebSecurityConfigurerAdapter` bean.
|
||
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
|
||
`EndpointRequest` can be used to create a `RequestMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||
`PathRequest` can be used to create a `RequestMatcher` for resources in commonly used locations.
|
||
|
||
|
||
|
||
[[web.security.spring-webflux]]
|
||
=== WebFlux Security
|
||
Similar to Spring MVC applications, you can secure your WebFlux applications by adding the `spring-boot-starter-security` dependency.
|
||
The default security configuration is implemented in `ReactiveSecurityAutoConfiguration` and `UserDetailsServiceAutoConfiguration`.
|
||
`ReactiveSecurityAutoConfiguration` imports `WebFluxSecurityConfiguration` for web security and `UserDetailsServiceAutoConfiguration` configures authentication, which is also relevant in non-web applications.
|
||
To switch off the default web application security configuration completely, you can add a bean of type `WebFilterChainProxy` (doing so does not disable the `UserDetailsService` configuration or Actuator's security).
|
||
|
||
To also switch off the `UserDetailsService` configuration, you can add a bean of type `ReactiveUserDetailsService` or `ReactiveAuthenticationManager`.
|
||
|
||
Access rules and the use of multiple Spring Security components such as OAuth 2 Client and Resource Server can be configured by adding a custom `SecurityWebFilterChain` bean.
|
||
Spring Boot provides convenience methods that can be used to override access rules for actuator endpoints and static resources.
|
||
`EndpointRequest` can be used to create a `ServerWebExchangeMatcher` that is based on the configprop:management.endpoints.web.base-path[] property.
|
||
|
||
`PathRequest` can be used to create a `ServerWebExchangeMatcher` for resources in commonly used locations.
|
||
|
||
For example, you can customize your security configuration by adding something like:
|
||
|
||
[source,java,indent=0,subs="verbatim"]
|
||
----
|
||
include::{docs-java}/features/security/springwebflux/MyWebFluxSecurityConfiguration.java[]
|
||
----
|
||
|
||
|
||
|
||
[[web.security.oauth2]]
|
||
=== 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 `OAuth2ClientProperties`.
|
||
The same properties are applicable to both servlet and reactive applications.
|
||
|
||
You can register multiple OAuth2 clients and providers under the `spring.security.oauth2.client` prefix, as shown in the following example:
|
||
|
||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||
----
|
||
spring:
|
||
security:
|
||
oauth2:
|
||
client:
|
||
registration:
|
||
my-client-1:
|
||
client-id: "abcd"
|
||
client-secret: "password"
|
||
client-name: "Client for user scope"
|
||
provider: "my-oauth-provider"
|
||
scope: "user"
|
||
redirect-uri: "https://my-redirect-uri.com"
|
||
client-authentication-method: "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: "https://my-redirect-uri.com"
|
||
client-authentication-method: "basic"
|
||
authorization-grant-type: "authorization_code"
|
||
|
||
provider:
|
||
my-oauth-provider:
|
||
authorization-uri: "https://my-auth-server/oauth/authorize"
|
||
token-uri: "https://my-auth-server/oauth/token"
|
||
user-info-uri: "https://my-auth-server/userinfo"
|
||
user-info-authentication-method: "header"
|
||
jwk-set-uri: "https://my-auth-server/token_keys"
|
||
user-name-attribute: "name"
|
||
----
|
||
|
||
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`:
|
||
|
||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||
----
|
||
spring:
|
||
security:
|
||
oauth2:
|
||
client:
|
||
provider:
|
||
oidc-provider:
|
||
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
|
||
----
|
||
|
||
By default, Spring Security's `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 `SecurityFilterChain` that resembles the following:
|
||
|
||
[source,java,indent=0,subs="verbatim"]
|
||
----
|
||
include::{docs-java}/features/security/oauth2/client/MyOAuthClientConfiguration.java[]
|
||
----
|
||
|
||
TIP: Spring Boot auto-configures an `InMemoryOAuth2AuthorizedClientService` which is used by Spring Security for the management of client registrations.
|
||
The `InMemoryOAuth2AuthorizedClientService` has limited capabilities and we recommend using it only for development environments.
|
||
For production environments, consider using a `JdbcOAuth2AuthorizedClientService` or creating your own implementation of `OAuth2AuthorizedClientService`.
|
||
|
||
|
||
|
||
[[web.security.oauth2.client.common-providers]]
|
||
===== OAuth2 client registration for common providers
|
||
For common OAuth2 and OpenID providers, including Google, Github, Facebook, and Okta, we provide a set of provider defaults (`google`, `github`, `facebook`, and `okta`, respectively).
|
||
|
||
If you do not need to customize these providers, you can set the `provider` attribute to the one for which you need to infer defaults.
|
||
Also, if the key for the client registration matches a default supported provider, Spring Boot infers that as well.
|
||
|
||
In other words, the two configurations in the following example use the Google provider:
|
||
|
||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||
----
|
||
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:
|
||
|
||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||
----
|
||
spring:
|
||
security:
|
||
oauth2:
|
||
resourceserver:
|
||
jwt:
|
||
jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
|
||
----
|
||
|
||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||
----
|
||
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 same properties are applicable for both servlet and reactive applications.
|
||
|
||
Alternatively, you can define your own `JwtDecoder` bean for servlet applications or a `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:
|
||
|
||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||
----
|
||
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.
|
||
|
||
Alternatively, you can define your own `OpaqueTokenIntrospector` bean for servlet applications or a `ReactiveOpaqueTokenIntrospector` for reactive applications.
|
||
|
||
|
||
|
||
[[web.security.oauth2.authorization-server]]
|
||
==== Authorization Server
|
||
Currently, Spring Security does not provide support for implementing an OAuth 2.0 Authorization Server.
|
||
However, this functionality is available from the {spring-security-oauth2}[Spring Security OAuth] project, which will eventually be superseded by Spring Security completely.
|
||
Until then, you can use the `spring-security-oauth2-autoconfigure` module to easily set up an OAuth 2.0 authorization server; see its https://docs.spring.io/spring-security-oauth2-boot/[documentation] for instructions.
|
||
|
||
|
||
|
||
[[web.security.saml2]]
|
||
=== SAML 2.0
|
||
|
||
|
||
|
||
[[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 `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:
|
||
|
||
[source,yaml,indent=0,subs="verbatim",configprops,configblocks]
|
||
----
|
||
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"
|
||
identityprovider:
|
||
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"
|
||
identityprovider:
|
||
verification:
|
||
credentials:
|
||
- certificate-location: "path-to-other-verification-cert"
|
||
entity-id: "remote-idp-entity-id2"
|
||
sso-url: "https://remoteidp2.sso.url"
|
||
----
|