mirror of
https://github.com/spring-projects/spring-security.git
synced 2025-10-28 13:18:45 +00:00
111 lines
5.5 KiB
Plaintext
111 lines
5.5 KiB
Plaintext
[[servlet-authentication-basic]]
|
|
= Basic Authentication
|
|
:figures: servlet/authentication/unpwd
|
|
|
|
This section provides details on how Spring Security provides support for https://tools.ietf.org/html/rfc7617[Basic HTTP Authentication] for servlet-based applications.
|
|
// FIXME: describe authenticationentrypoint, authenticationfailurehandler, authenticationsuccesshandler
|
|
|
|
This section describes how HTTP Basic Authentication works within Spring Security.
|
|
First, we see the https://tools.ietf.org/html/rfc7235#section-4.1[WWW-Authenticate] header is sent back to an unauthenticated client:
|
|
|
|
.Sending WWW-Authenticate Header
|
|
[.invert-dark]
|
|
image::{figures}/basicauthenticationentrypoint.png[]
|
|
|
|
The preceding figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
|
|
|
|
image:{icondir}/number_1.png[] First, a user makes an unauthenticated request to the resource `/private` for which it is not authorized.
|
|
|
|
image:{icondir}/number_2.png[] Spring Security's xref:servlet/authorization/authorize-http-requests.adoc[`AuthorizationFilter`] indicates that the unauthenticated request is __Denied__ by throwing an `AccessDeniedException`.
|
|
|
|
image:{icondir}/number_3.png[] Since the user is not authenticated, xref:servlet/architecture.adoc#servlet-exceptiontranslationfilter[`ExceptionTranslationFilter`] initiates __Start Authentication__.
|
|
The configured xref:servlet/authentication/architecture.adoc#servlet-authentication-authenticationentrypoint[`AuthenticationEntryPoint`] is an instance of javadoc:org.springframework.security.web.authentication.www.BasicAuthenticationEntryPoint[], which sends a WWW-Authenticate header.
|
|
The `RequestCache` is typically a `NullRequestCache` that does not save the request since the client is capable of replaying the requests it originally requested.
|
|
|
|
[NOTE]
|
|
====
|
|
The default HTTP Basic Auth Provider will suppress both Response body and `WWW-Authenticate` header in the 401 response when the request was made with a `X-Requested-By: XMLHttpRequest` header.
|
|
This allows frontends to implement their own authentication code, instead of triggering the browser login dialog.
|
|
To override, implement your own javadoc:org.springframework.security.web.authentication.www.BasicAuthenticationEntryPoint[].
|
|
====
|
|
|
|
When a client receives the `WWW-Authenticate` header, it knows it should retry with a username and password.
|
|
The following image shows the flow for the username and password being processed:
|
|
|
|
[[servlet-authentication-basicauthenticationfilter]]
|
|
.Authenticating Username and Password
|
|
[.invert-dark]
|
|
image::{figures}/basicauthenticationfilter.png[]
|
|
|
|
The preceding figure builds off our xref:servlet/architecture.adoc#servlet-securityfilterchain[`SecurityFilterChain`] diagram.
|
|
|
|
|
|
image:{icondir}/number_1.png[] When the user submits their username and password, the `BasicAuthenticationFilter` creates a `UsernamePasswordAuthenticationToken`, which is a type of xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[`Authentication`] by extracting the username and password from the `HttpServletRequest`.
|
|
|
|
image:{icondir}/number_2.png[] Next, the `UsernamePasswordAuthenticationToken` is passed into the `AuthenticationManager` to be authenticated.
|
|
The details of what `AuthenticationManager` looks like depend on how the xref:servlet/authentication/passwords/index.adoc#servlet-authentication-unpwd[user information is stored].
|
|
|
|
image:{icondir}/number_3.png[] If authentication fails, then __Failure__.
|
|
|
|
. The xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder] is cleared out.
|
|
. `RememberMeServices.loginFail` is invoked.
|
|
If remember me is not configured, this is a no-op.
|
|
See the javadoc:org.springframework.security.web.authentication.RememberMeServices[] interface in the Javadoc.
|
|
. `AuthenticationEntryPoint` is invoked to trigger the WWW-Authenticate to be sent again.
|
|
See the javadoc:org.springframework.security.web.AuthenticationEntryPoint[] interface in the Javadoc.
|
|
|
|
image:{icondir}/number_4.png[] If authentication is successful, then __Success__.
|
|
|
|
. The xref:servlet/authentication/architecture.adoc#servlet-authentication-authentication[Authentication] is set on the xref:servlet/authentication/architecture.adoc#servlet-authentication-securitycontextholder[SecurityContextHolder].
|
|
. `RememberMeServices.loginSuccess` is invoked.
|
|
If remember me is not configured, this is a no-op.
|
|
See the javadoc:org.springframework.security.web.authentication.RememberMeServices[] interface in the Javadoc.
|
|
. The `BasicAuthenticationFilter` invokes `FilterChain.doFilter(request,response)` to continue with the rest of the application logic.
|
|
See the javadoc:org.springframework.security.web.authentication.www.BasicAuthenticationFilter[] Class in the Javadoc
|
|
|
|
By default, Spring Security's HTTP Basic Authentication support is enabled.
|
|
However, as soon as any servlet based configuration is provided, HTTP Basic must be explicitly provided.
|
|
|
|
The following example shows a minimal, explicit configuration:
|
|
|
|
.Explicit HTTP Basic Configuration
|
|
[tabs]
|
|
======
|
|
Java::
|
|
+
|
|
[source,java,role="primary"]
|
|
----
|
|
@Bean
|
|
public SecurityFilterChain filterChain(HttpSecurity http) {
|
|
http
|
|
// ...
|
|
.httpBasic(withDefaults());
|
|
return http.build();
|
|
}
|
|
----
|
|
|
|
XML::
|
|
+
|
|
[source,xml,role="secondary"]
|
|
----
|
|
<http>
|
|
<!-- ... -->
|
|
<http-basic />
|
|
</http>
|
|
----
|
|
|
|
Kotlin::
|
|
+
|
|
[source,kotlin,role="secondary"]
|
|
----
|
|
@Bean
|
|
open fun filterChain(http: HttpSecurity): SecurityFilterChain {
|
|
http {
|
|
// ...
|
|
httpBasic { }
|
|
}
|
|
return http.build()
|
|
}
|
|
----
|
|
======
|