If Spring Security is in 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 implement method-level security into your web application, you can also add the
@EnableGlobalMethodSecurity
annotation with the desired settings.
UserDetailsService
is
provided for a single user by default. The username is user
and the password is random and is printed
at the WARN level when the application starts, as shown in the following example:
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.
org.springframework.boot.autoconfigure.security
category is configured to log WARN
level messages. Otherwise, the default password is not displayed.
You can change the username and password by specifying spring.security.user.name
and spring.security.user.password
.
The main functions that are available to you by default in a web application are the following:
The
UserDetailsService
bean (orReactiveUserDetailsService
in the case of a WebFlux application) with in-memory storage and one user with a generated password (for user properties, seeSecurityProperties.User
).Log in using forms or secure using HTTP Basic (depending on the
Accept
header in the request) for the entire application (including actuator endpoints if the actuator is in classpath).DefaultAuthenticationEventPublisher
for publishing authentication events.
You can pass another AuthenticationEventPublisher
by adding a bean for it.
Security for MVC
The default security configuration is implemented in SecurityAutoConfiguration
and
UserDetailsServiceAutoConfiguration
. SecurityAutoConfiguration
imports SpringBootWebSecurityConfiguration
for web security, and UserDetailsServiceAutoConfiguration
configures authentication, which is also
relevant for non-web applications. To completely disable the default web application security configuration or
combine multiple Spring Security components such as the OAuth2 resource client and server, add a bean of type SecurityFilterChain
(with the UserDetailsService
configuration or security security for Actuator will not be disabled).
To, among other things, disable the UserDetailsService
configuration, you can add a bean like UserDetailsService
,
AuthenticationProvider
or AuthenticationManager
.
Access rules can be overridden by
adding a custom SecurityFilterChain
or WebSecurityConfigurerAdapter
bean. Spring Boot
provides helper methods that you can use to override access rules for actuator endpoints and static resources.
EndpointRequest
can be used to create a RequestMatcher
that is based on the management.endpoints.web.base-path
property. PathRequest
can be used to create a RequestMatcher
for resources located in
frequently used locations.
Security in WebFlux
Similar to Spring applications MVC, 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 for non-web
applications. To completely disable the default web application security configuration, you can add a bean like
WebFilterChainProxy
(this does not disable the UserDetailsService
configuration or
Actuator security).
To also disable the UserDetailsService
configuration, you can add a bean
like ReactiveUserDetailsService
or ReactiveAuthenticationManager
.
Access rules and
use of multiple Spring beans Security, such as the OAuth 2 resource client and server, can be configured by adding a
custom SecurityWebFilterChain
bean. Spring Boot provides helper methods that you can use to override
access rules for actuator endpoints and static resources. EndpointRequest
can be used to create a
ServerWebExchangeMatcher
, which is based on the management.endpoints.web.base-path
property.
PathRequest
can be used to create a ServerWebExchangeMatcher
for
resources located in frequently used locations.
For example, you can configure security controls by adding something like:
import org.springframework.boot.autoconfigure.security.reactive.PathRequest;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.web.server.ServerHttpSecurity;
import org.springframework.security.web.server.SecurityWebFilterChain;
import static org.springframework.security.config.Customizer.withDefaults;
@Configuration(proxyBeanMethods = false)
public class MyWebFluxSecurityConfiguration {
@Bean
public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
http.authorizeExchange((exchange) -> {
exchange.matchers(PathRequest.toStaticResources().atCommonLocations()).permitAll();
exchange.pathMatchers("/foo", "/bar").authenticated();
});
http.formLogin(withDefaults());
return http.build();
}
}
import org.springframework.boot.autoconfigure.security.reactive.PathRequest
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.web.server.ServerHttpSecurity
import org.springframework.security.web.server.SecurityWebFilterChain
@Configuration(proxyBeanMethods = false)
class MyWebFluxSecurityConfiguration {
@Bean
fun springSecurityFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
http.authorizeExchange { spec ->
spec.matchers(PathRequest.toStaticResources().atCommonLocations()).permitAll()
spec.pathMatchers("/foo", "/bar").authenticated()
}
http.formLogin()
return http.build()
}
}
OAuth2
OAuth2 is a widely used authorization system that is supported by Spring.
Client
If your classpath has
spring-security-oauth2-client
, you can use some auto-configuration features to install OAuth2/Open ID
Connect clients. This configuration
uses properties from OAuth2ClientProperties
. These same properties apply to both servlets and reactive
applications.
You can register multiple OAuth2 clients and providers under the spring.security.oauth2.client
prefix, as shown in the following example:
spring.security.oauth2.client.registration.my-client-1.client-id=abcd
spring.security.oauth2.client.registration.my-client-1.client-secret=password
spring.security.oauth2.client.registration.my-client-1.client-name=Client for user scope
spring.security.oauth2.client.registration.my-client-1.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-1.scope=user
spring.security.oauth2.client.registration.my-client-1.redirect-uri=https://my-redirect-uri.com
spring.security.oauth2.client.registration.my-client-1.client-authentication-method=basic
spring.security.oauth2.client.registration.my-client-1.authorization-grant-type=authorization-code
spring.security.oauth2.client.registration.my-client-2.client-id=abcd
spring.security.oauth2.client.registration.my-client-2.client-secret=password
spring.security.oauth2.client.registration.my-client-2.client-name=Client for email scope
spring.security.oauth2.client.registration.my-client-2.provider=my-oauth-provider
spring.security.oauth2.client.registration.my-client-2.scope=email
spring.security.oauth2.client.registration.my-client-2.redirect-uri=https://my-redirect-uri.com
spring.security.oauth2.client.registration.my-client-2.client-authentication-method=basic
spring.security.oauth2.client.registration.my-client-2.authorization-grant-type=authorization_code
spring.security.oauth2.client.provider.my-oauth-provider.authorization-uri=https://my-auth-server/oauth/authorize
spring.security.oauth2.client.provider.my-oauth-provider.token-uri=https://my-auth-server/oauth/token
spring.security.oauth2.client.provider.my-oauth-provider.user-info-uri=https://my-auth-server/userinfo
spring.security.oauth2.client.provider.my-oauth-provider.user-info-authentication-method=header
spring.security.oauth2.client.provider.my-oauth-provider.jwk-set-uri=https://my-auth-server/token_keys
spring.security.oauth2.client.provider.my-oauth-provider.user-name-attribute=name
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 OpenID Connect discovery, the configuration
can be further simplified. The issuer must be configured with issuer-uri
, which is a URI that adds a
claim that the given URI is the issuer identifier. For example, if the issuer-uri
passed is
"https://example.com", then the OpenID Provider Configuration Request
will be made to
"https://example.com/.well-known/openid-configuration". The expected result is an OpenID Provider
Configuration Response
. The following example shows how the OpenID Connect provider can be configured
using issuer-uri
:
spring.security.oauth2.client.provider.oidc-provider.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
spring:
security:
oauth2:
client:
provider:
oidc-provider:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
By default, the OAuth2LoginAuthenticationFilter
in Spring Security only processes URLs
corresponding /login/oauth2/code/*
. If you want to configure redirect-uri
to use a
different template, you need to create a configuration to handle that template. For example, for servlet
applications, you can add your own SecurityFilterChain
, which would be similar to the following:
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;
@Configuration(proxyBeanMethods = false)
public class MyOAuthClientConfiguration {
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http.authorizeRequests((requests) -> requests.anyRequest().authenticated());
http.oauth2Login((login) -> login.redirectionEndpoint().baseUri("custom-callback"));
return http.build();
}
}
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration
import org.springframework.security.config.annotation.web.builders.HttpSecurity
import org.springframework.security.web.SecurityFilterChain
@Configuration(proxyBeanMethods = false)
class MyOAuthClientConfiguration {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http.authorizeRequests().anyRequest().authenticated()
http.oauth2Login().redirectionEndpoint().baseUri("custom-callback")
return http.build()
}
}
InMemoryOAuth2AuthorizedClientService
,
which is used by Spring Security to manage client registration procedures. InMemoryOAuth2AuthorizedClientService
has limited functionality, so we recommend using it only in development environments. In production environments,
use JdbcOAuth2AuthorizedClientService
or create your own implementation of OAuth2AuthorizedClientService
.
Registering OAuth2 clients for common providers
For common OAuth2 providers and OpenID, including
Google, Github, Facebook and Okta, we provide a set of default providers (google
, github
,
facebook
and okta
, respectively).
If you do not need to configure these providers,
you can set the provider
attribute for the one for which you want to display default values.
Additionally, if the client registration key matches a default supported provider, Spring Boot will detect that as
well.
In other words, the two configurations in the following example use the Google provider:
spring.security.oauth2.client.registration.my-client.client-id=abcd
spring.security.oauth2.client.registration.my-client.client-secret=password
spring.security.oauth2.client.registration.my-client.provider=google
spring.security.oauth2.client.registration.google.client-id=abcd
spring.security.oauth2.client.registration.google.client-secret=password
spring:
security:
oauth2:
client:
registration:
my-client:
client-id: "abcd"
client-secret: "password"
provider: "google"
google:
client-id: "abcd"
client-secret: "password"
Resource Server
If you have spring-security-oauth2-resource-server
in your classpath,
Spring Boot can install OAuth2 resource server. For JWT configuration, you must specify a JWK Set URI or OIDC Issuer
URI, as shown in the following examples:
spring. security.oauth2.resourceserver.jwt.jwk-set-uri=https://example.com/oauth2/default/v1/keys
spring:
security:
oauth2:
resourceserver:
jwt:
jwk-set-uri: "https://example.com/oauth2/default/v1/keys"
spring.security.oauth2.resourceserver. jwt.issuer-uri=https://dev-123456.oktapreview.com/oauth2/default/
spring:
security:
oauth2:
resourceserver:
jwt:
issuer-uri: "https://dev-123456.oktapreview.com/oauth2/default/"
spring.security.oauth2.resourceserver.jwt.public-key-location
property, where the value must point to a file containing the public key encoded in PEM x509 format.
The same properties apply to both servlet and reactive applications.
You can also define your own
JwtDecoder
bean for servlet applications or 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:
spring.security.oauth2.resourceserver.opaquetoken.introspection-uri=https://example.com/check-token
spring.security.oauth2.resourceserver.opaquetoken.client-id=my-client-id
spring.security.oauth2.resourceserver.opaquetoken.client-secret=my-client-secret
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 apply to both servlet and reactive applications.
Alternatively, you
can define your own bean OpaqueTokenIntrospector
for servlet applications or ReactiveOpaqueTokenIntrospector
for reactive applications.
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 OAuth project, which will
eventually be superseded by Spring Security. Until then, you can use the
spring-security-oauth2-autoconfigure
module to easily configure an OAuth 2.0 authorization server; see
documentation for instructions.