[[features.security]]
== 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}#jc-method[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 INFO level when the application starts, as shown in the following example:

[indent=0]
----
	Using generated security password: 78fa095d-3f4c-48b1-ad50-e24c31d5cf35
----

NOTE: If you fine-tune your logging configuration, ensure that the `org.springframework.boot.autoconfigure.security` category is set to log `INFO`-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.



[[features.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.



[[features.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[]
----



[[features.security.oauth2]]
=== OAuth2
https://oauth.net/2/[OAuth2] is a widely used authorization framework that is supported by Spring.



[[features.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 an 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 the 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`.



[[features.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"
----



[[features.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 via 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.



[[features.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.



[[features.security.saml2]]
=== SAML 2.0



[[features.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"
----



[[features.security.actuator]]
=== Actuator Security
For security purposes, all actuators other than `/health` are disabled by default.
The configprop:management.endpoints.web.exposure.include[] property can be used to enable the actuators.

If Spring Security is on the classpath and no other `WebSecurityConfigurerAdapter` or `SecurityFilterChain` bean is present, all actuators other than `/health` are secured by Spring Boot auto-configuration.
If you define a custom `WebSecurityConfigurerAdapter` or `SecurityFilterChain` bean, Spring Boot auto-configuration will back off and you will be in full control of actuator access rules.

NOTE: Before setting the `management.endpoints.web.exposure.include`, ensure that the exposed actuators do not contain sensitive information and/or are secured by placing them behind a firewall or by something like Spring Security.



[[features.security.actuator.csrf]]
==== Cross Site Request Forgery Protection
Since Spring Boot relies on Spring Security's defaults, CSRF protection is turned on by default.
This means that the actuator endpoints that require a `POST` (shutdown and loggers endpoints), `PUT` or `DELETE` will get a 403 forbidden error when the default security configuration is in use.

NOTE: We recommend disabling CSRF protection completely only if you are creating a service that is used by non-browser clients.

Additional information about CSRF protection can be found in the {spring-security-docs}#csrf[Spring Security Reference Guide].
