Spring Security

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.

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 (or ReactiveUserDetailsService in the case of a WebFlux application) with in-memory storage and one user with a generated password (for user properties, see SecurityProperties.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()
    }
}

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/"

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.