spring-security/docs/modules/ROOT/pages/servlet/authentication/adaptive.adoc

= Adaptive Authentication

Since authentication needs can vary from person-to-person and even from one login attempt to the next, Spring Security supports adapting authentication requirements to each situation.

Some of the most common applications of this principal are:

1. *Re-authentication* - Users need to provide authentication again in order to enter an area of elevated security
2. *Multi-factor Authentication* - Users need more than one authentication mechanism to pass in order to access secured resources
3. *Authorizing More Scopes* - Users are allowed to consent to a subset of scopes from an OAuth 2.0 Authorization Server.
Then, if later on a scope that they did not grant is needed, consent can be re-requested for just that scope.
4. *Opting-in to Stronger Authentication Mechanisms* - Users may not be ready yet to start using MFA, but the application wants to allow the subset of security-minded users to opt-in.
5. *Requiring Additional Steps for Suspicious Logins* - The application may notice that the user's IP address has changed, that they are behind a VPN, or some other consideration that requires additional verification

[[re-authentication]]
== Re-authentication

The most common of these is re-authentication.
Imagine an application configured in the following way:

include-code::./SimpleConfiguration[tag=httpSecurity,indent=0]

By default, this application has two authentication mechanisms that it allows, meaning that the user could use either one and be fully-authenticated.

If there is a set of endpoints that require a specific factor, we can specify that in `authorizeHttpRequests` as follows:

include-code::./RequireOttConfiguration[tag=httpSecurity,indent=0]
<1> - States that all `/profile/**` endpoints require one-time-token login to be authorized

Given the above configuration, users can log in with any mechanism that you support.
And, if they want to visit the profile page, then Spring Security will redirect them to the One-Time-Token Login page to obtain it.

In this way, the authority given to a user is directly proportional to the amount of proof given.
This adaptive approach allows users to give only the proof needed to perform their intended operations.

[[multi-factor-authentication]]
== Multi-Factor Authentication

You may require that all users require both One-Time-Token login and Username/Password login to access any part of your site.

To require both, you can state an authorization rule with `anyRequest` like so:

include-code::./ListAuthoritiesConfiguration[tag=httpSecurity,indent=0]
<1> - This states that both `FACTOR_PASSWORD` and `FACTOR_OTT` are needed to use any part of the application

Spring Security behind the scenes knows which endpoint to go to depending on which authority is missing.
If the user logged in initially with their username and password, then Spring Security redirects to the One-Time-Token Login page.
If the user logged in initially with a token, then Spring Security redirects to the Username/Password Login page.

[[authorization-manager-factory]]
=== Requiring MFA For All Endpoints

Specifying all authorities for each request pattern could be unwanted boilerplate:

include-code::./ListAuthoritiesEverywhereConfiguration[tag=httpSecurity,indent=0]
<1> - Since all authorities need to be specified for each endpoint, deploying MFA in this way can create unwanted boilerplate

This can be remedied by publishing an `AuthorizationManagerFactory` bean like so:

include-code::./UseAuthorizationManagerFactoryConfiguration[tag=authorizationManagerFactoryBean,indent=0]

This yields a more familiar configuration:

include-code::./UseAuthorizationManagerFactoryConfiguration[tag=httpSecurity,indent=0]

[[enable-global-mfa]]
=== @EnableGlobalMultiFactorAuthentication

You can simplify the configuration even further by using `@EnableGlobalMultiFactorAuthentication` to create the `AuthorizationManagerFactory` for you.

include-code::./EnableGlobalMultiFactorAuthenticationConfiguration[tag=enable-global-mfa,indent=0]


[[obtaining-more-authorization]]
== Authorizing More Scopes

You can also configure exception handling to direct Spring Security on how to obtain a missing scope.

Consider an application that requires a specific OAuth 2.0 scope for a given endpoint:

include-code::./ScopeConfiguration[tag=httpSecurity,indent=0]

If this is also configured with an `AuthorizationManagerFactory` bean like this one:

include-code::./MissingAuthorityConfiguration[tag=authorizationManagerFactoryBean,indent=0]

Then the application will require an X.509 certificate as well as authorization from an OAuth 2.0 authorization server.

In the event that the user does not consent to `profile:read`, this application as it stands will issue a 403.
However, if you have a way for the application to re-ask for consent, then you can implement this in an `AuthenticationEntryPoint` like the following:

include-code::./MissingAuthorityConfiguration[tag=authenticationEntryPoint,indent=0]

Then, your filter chain declaration can bind this entry point to the given authority like so:

include-code::./MissingAuthorityConfiguration[tag=httpSecurity,indent=0]

[[custom-authorization-manager-factory]]
== Programmatically Decide Which Authorities Are Required

`AuthorizationManager` is the core interface for making authorization decisions.
Consider an authorization manager that looks at the logged in user to decide which factors are necessary:

include-code::./CustomAuthorizationManagerFactory[tag=authorizationManager,indent=0]

In this case, using One-Time-Token is only required for those who have opted in.

This can then be enforced by a custom `AuthorizationManagerFactory` implementation:

include-code::./CustomAuthorizationManagerFactory[tag=authorizationManagerFactory,indent=0]