OAuth 2.0 Test Support Docs

- Added WebTestClient documentation
- Updated MockMvc documentation to align

Fixes gh-8050

docs/manual/src/docs/asciidoc/_includes/reactive/test.adoc

@@ -149,8 +149,401 @@ this.rest
 	...
 ----
 
+[[webflux-testing-oauth2]]
+=== Testing OAuth 2.0
 
-=== Testing Bearer Authentication
+When it comes to OAuth 2.0, the same principles covered earlier still apply: Ultimately, it depends on what your method under test is expecting to be in the `SecurityContextHolder`.
+
+For example, for a controller that looks like this:
+
+[source,java]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(Principal user) {
+    return Mono.just(user.getName());
+}
+----
+
+There's nothing OAuth2-specific about it, so you will likely be able to simply <<test-erms,use `@WithMockUser`>> and be fine.
+
+But, in cases where your controllers are bound to some aspect of Spring Security's OAuth 2.0 support, like the following:
+
+[source,java]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(@AuthenticationPrincipal OidcUser user) {
+    return Mono.just(user.getIdToken().getSubject());
+}
+----
+
+then Spring Security's test support can come in handy.
+
+[[webflux-testing-oidc-login]]
+=== Testing OIDC Login
+
+Testing the method above with `WebTestClient` would require simulating some kind of grant flow with an authorization server.
+Certainly this would be a daunting task, which is why Spring Security ships with support for removing this boilerplate.
+
+For example, we can tell Spring Security to include a default `OidcUser` using the `SecurityMockServerConfigurers#oidcLogin` method, like so:
+
+[source,java]
+----
+client
+    .mutateWith(mockOidcLogin()).get().uri("/endpoint").exchange();
+----
+
+What this will do is configure the associated `MockServerRequest` with an `OidcUser` that includes a simple `OidcIdToken`, `OidcUserInfo`, and `Collection` of granted authorities.
+
+Specifically, it will include an `OidcIdToken` with a `sub` claim set to `user`:
+
+[source,json]
+----
+assertThat(user.getIdToken().getClaim("sub")).isEqualTo("user");
+----
+
+an `OidcUserInfo` with no claims set:
+
+[source,json]
+----
+assertThat(user.getUserInfo().getClaims()).isEmpty();
+----
+
+and a `Collection` of authorities with just one authority, `SCOPE_read`:
+
+[source,json]
+----
+assertThat(user.getAuthorities()).hasSize(1);
+assertThat(user.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));
+----
+
+Spring Security does the necessary work to make sure that the `OidcUser` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+
+Further, it also links that `OidcUser` to a simple instance of `OAuth2AuthorizedClient` that it deposits into an `WebSessionOAuth2ServerAuthorizedClientRepository`.
+This can be handy if your tests <<webflux-testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>..
+
+[[webflux-testing-oidc-login-authorities]]
+==== Configuring Authorities
+
+In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
+
+In this case, you can supply what granted authorities you need using the `authorities()` method:
+
+[source,java]
+----
+client
+    .mutateWith(mockOidcLogin()
+        .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
+    )
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-oidc-login-claims]]
+==== Configuring Claims
+
+And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0.
+
+Let's say, for example, that you've got a `user_id` claim that indicates the user's id in your system.
+You might access it like so in a controller:
+
+[source,java]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(@AuthenticationPrincipal OidcUser oidcUser) {
+    String userId = oidcUser.getIdToken().getClaim("user_id");
+    // ...
+}
+----
+
+In that case, you'd want to specify that claim with the `idToken()` method:
+
+[source,java]
+----
+client
+    .mutateWith(mockOidcLogin()
+        .idToken(token -> token.claim("user_id", "1234"))
+    )
+    .get().uri("/endpoint").exchange();
+----
+
+since `OidcUser` collects its claims from `OidcIdToken`.
+
+[[webflux-testing-oidc-login-user]]
+==== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
+
+* `userInfo(OidcUserInfo.Builder)` - For configuring the `OidcUserInfo` instance
+* `clientRegistration(ClientRegistration)` - For configuring the associated `OAuth2AuthorizedClient` with a given `ClientRegistration`
+* `oidcUser(OidcUser)` - For configuring the complete `OidcUser` instance
+
+That last one is handy if you:
+1. Have your own implementation of `OidcUser`, or
+2. Need to change the name attribute
+
+For example, let's say that your authorization server sends the principal name in the `user_name` claim instead of the `sub` claim.
+In that case, you can configure an `OidcUser` by hand:
+
+[source,java]
+----
+OidcUser oidcUser = new DefaultOidcUser(
+        AuthorityUtils.createAuthorityList("SCOPE_message:read"),
+        Collections.singletonMap("user_name", "foo_user"),
+        "user_name");
+
+client
+    .mutateWith(mockOidcLogin().oidcUser(oidcUser))
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-oauth2-login]]
+=== Testing OAuth 2.0 Login
+
+As with <<webflux-testing-oidc-login,testing OIDC login>>, testing OAuth 2.0 Login presents a similar challenge of mocking a grant flow.
+And because of that, Spring Security also has test support for non-OIDC use cases.
+
+Let's say that we've got a controller that gets the logged-in user as an `OAuth2User`:
+
+[source,java]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(@AuthenticationPrincipal OAuth2User oauth2User) {
+    return Mono.just(oauth2User.getAttribute("sub"));
+}
+----
+
+In that case, we can tell Spring Security to include a default `OAuth2User` using the `SecurityMockServerConfigurers#oauth2User` method, like so:
+
+[source,java]
+----
+client
+    .mutateWith(mockOAuth2Login())
+    .get().uri("/endpoint").exchange();
+----
+
+What this will do is configure the associated `MockServerRequest` with an `OAuth2User` that includes a simple `Map` of attributes and `Collection` of granted authorities.
+
+Specifically, it will include a `Map` with a key/value pair of `sub`/`user`:
+
+[source,json]
+----
+assertThat((String) user.getAttribute("sub")).isEqualTo("user");
+----
+
+and a `Collection` of authorities with just one authority, `SCOPE_read`:
+
+[source,json]
+----
+assertThat(user.getAuthorities()).hasSize(1);
+assertThat(user.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));
+----
+
+Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+
+Further, it also links that `OAuth2User` to a simple instance of `OAuth2AuthorizedClient` that it deposits in an `WebSessionOAuth2ServerAuthorizedClientRepository`.
+This can be handy if your tests <<webflux-testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>.
+
+[[webflux-testing-oauth2-login-authorities]]
+==== Configuring Authorities
+
+In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
+
+In this case, you can supply what granted authorities you need using the `authorities()` method:
+
+[source,java]
+----
+client
+    .mutateWith(mockOAuth2Login()
+        .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
+    )
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-oauth2-login-claims]]
+==== Configuring Claims
+
+And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0.
+
+Let's say, for example, that you've got a `user_id` attribute that indicates the user's id in your system.
+You might access it like so in a controller:
+
+[source,java]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(@AuthenticationPrincipal OAuth2User oauth2User) {
+    String userId = oauth2User.getAttribute("user_id");
+    // ...
+}
+----
+
+In that case, you'd want to specify that attribute with the `attributes()` method:
+
+[source,java]
+----
+client
+    .mutateWith(mockOAuth2Login()
+        .attributes(attrs -> attrs.put("user_id", "1234"))
+    )
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-oauth2-login-user]]
+==== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
+
+* `clientRegistration(ClientRegistration)` - For configuring the associated `OAuth2AuthorizedClient` with a given `ClientRegistration`
+* `oauth2User(OAuth2User)` - For configuring the complete `OAuth2User` instance
+
+That last one is handy if you:
+1. Have your own implementation of `OAuth2User`, or
+2. Need to change the name attribute
+
+For example, let's say that your authorization server sends the principal name in the `user_name` claim instead of the `sub` claim.
+In that case, you can configure an `OAuth2User` by hand:
+
+[source,java]
+----
+OAuth2User oauth2User = new DefaultOAuth2User(
+        AuthorityUtils.createAuthorityList("SCOPE_message:read"),
+        Collections.singletonMap("user_name", "foo_user"),
+        "user_name");
+
+client
+    .mutateWith(mockOAuth2Login().oauth2User(oauth2User))
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-oauth2-client]]
+=== Testing OAuth 2.0 Clients
+
+Independent of how your user authenticates, you may have other tokens and client registrations that are in play for the request you are testing.
+For example, your controller may be relying on the client credentials grant to get a token that isn't associated with the user at all:
+
+[source,json]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(@RegisteredOAuth2AuthorizedClient("my-app") OAuth2AuthorizedClient authorizedClient) {
+    return this.webClient.get()
+        .attributes(oauth2AuthorizedClient(authorizedClient))
+        .retrieve()
+        .bodyToMono(String.class);
+}
+----
+
+Simulating this handshake with the authorization server could be cumbersome.
+Instead, you can use `SecurityMockServerConfigurers#oauth2Client` to add a `OAuth2AuthorizedClient` into an `WebSessionOAuth2ServerAuthorizedClientRepository`:
+
+[source,java]
+----
+client
+    .mutateWith(mockOAuth2Client("my-app"))
+    .get().uri("/endpoint").exchange();
+----
+
+If your application isn't already using an `WebSessionOAuth2ServerAuthorizedClientRepository`, then you can supply one as a `@TestConfiguration`:
+
+[source,java]
+----
+@TestConfiguration
+static class AuthorizedClientConfig {
+    @Bean
+    OAuth2ServerAuthorizedClientRepository authorizedClientRepository() {
+        return new WebSessionOAuth2ServerAuthorizedClientRepository();
+    }
+}
+----
+
+What this will do is create an `OAuth2AuthorizedClient` that has a simple `ClientRegistration`, `OAuth2AccessToken`, and resource owner name.
+
+Specifically, it will include a `ClientRegistration` with a client id of "test-client" and client secret of "test-secret":
+
+[source,json]
+----
+assertThat(authorizedClient.getClientRegistration().getClientId()).isEqualTo("test-client");
+assertThat(authorizedClient.getClientRegistration().getClientSecret()).isEqualTo("test-secret");
+----
+
+a resource owner name of "user":
+
+[source,json]
+----
+assertThat(authorizedClient.getPrincipalName()).isEqualTo("user");
+----
+
+and an `OAuth2AccessToken` with just one scope, `read`:
+
+[source,json]
+----
+assertThat(authorizedClient.getAccessToken().getScopes()).hasSize(1);
+assertThat(authorizedClient.getAccessToken().getScopes()).containsExactly("read");
+----
+
+Spring Security does the necessary work to make sure that the `OAuth2AuthorizedClient` instance is available in the associated `HttpSession`.
+That means that it can be retrieved from an `WebSessionOAuth2ServerAuthorizedClientRepository`.
+
+[[webflux-testing-oauth2-client-scopes]]
+==== Configuring Scopes
+
+In many circumstances, the OAuth 2.0 access token comes with a set of scopes.
+If your controller inspects these, say like so:
+
+[source,json]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(@RegisteredOAuth2AuthorizedClient("my-app") OAuth2AuthorizedClient authorizedClient) {
+    Set<String> scopes = authorizedClient.getAccessToken().getScopes();
+    if (scopes.contains("message:read")) {
+        return this.webClient.get()
+            .attributes(oauth2AuthorizedClient(authorizedClient))
+            .retrieve()
+            .bodyToMono(String.class);
+    }
+    // ...
+}
+----
+
+then you can configure the scope using the `accessToken()` method:
+
+[source,java]
+----
+client
+    .mutateWith(mockOAuth2Client("my-app")
+        .accessToken(new OAuth2AccessToken(BEARER, "token", null, null, Collections.singleton("message:read"))))
+    )
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-oauth2-client-registration]]
+==== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
+
+* `principalName(String)` - For configuring the resource owner name
+* `clientRegistration(Consumer<ClientRegistration.Builder>)` - For configuring the associated `ClientRegistration`
+* `clientRegistration(ClientRegistration)` - For configuring the complete `ClientRegistration`
+
+That last one is handy if you want to use a real `ClientRegistration`
+
+For example, let's say that you are wanting to use one of your app's `ClientRegistration` definitions, as specified in your `application.yml`.
+
+In that case, your test can autowire the `ReactiveClientRegistrationRepository` and look up the one your test needs:
+
+[source,java]
+----
+@Autowired
+ReactiveClientRegistrationRepository clientRegistrationRepository;
+
+// ...
+
+client
+    .mutateWith(mockOAuth2Client()
+        .clientRegistration(this.clientRegistrationRepository.findByRegistrationId("facebook"))
+    )
+    .get().uri("/exchange").exchange();
+----
+
+[[webflux-testing-jwt]]
+=== Testing JWT Authentication
 
 In order to make an authorized request on a resource server, you need a bearer token.
 If your resource server is configured for JWTs, then this would mean that the bearer token needs to be signed and then encoded according to the JWT specification.
@@ -268,3 +661,120 @@ client
 ----
 
 Note that as an alternative to these, you can also mock the `ReactiveJwtDecoder` bean itself with a `@MockBean` annotation.
+
+[[webflux-testing-opaque-token]]
+=== Testing Opaque Token Authentication
+
+Similar to <<webflux-testing-jwt,JWTs>>, opaque tokens require an authorization server in order to verify their validity, which can make testing more difficult.
+To help with that, Spring Security has test support for opaque tokens.
+
+Let's say that we've got a controller that retrieves the authentication as a `BearerTokenAuthentication`:
+
+[source,java]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(BearerTokenAuthentication authentication) {
+    return Mono.just((String) authentication.getTokenAttributes("sub"));
+}
+----
+
+In that case, we can tell Spring Security to include a default `BearerTokenAuthentication` using the `SecurityMockServerConfigurers#opaqueToken` method, like so:
+
+[source,java]
+----
+client
+    .mutateWith(mockOpaqueToken())
+    .get().uri("/endpoint").exchange();
+----
+
+What this will do is configure the associated `MockHttpServletRequest` with a `BearerTokenAuthentication` that includes a simple `OAuth2AuthenticatedPrincipal`, `Map` of attributes, and `Collection` of granted authorities.
+
+Specifically, it will include a `Map` with a key/value pair of `sub`/`user`:
+
+[source,json]
+----
+assertThat((String) token.getTokenAttributes().get("sub")).isEqualTo("user");
+----
+
+and a `Collection` of authorities with just one authority, `SCOPE_read`:
+
+[source,json]
+----
+assertThat(token.getAuthorities()).hasSize(1);
+assertThat(token.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));
+----
+
+Spring Security does the necessary work to make sure that the `BearerTokenAuthentication` instance is available for your controller methods.
+
+[[webflux-testing-opaque-token-authorities]]
+==== Configuring Authorities
+
+In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
+
+In this case, you can supply what granted authorities you need using the `authorities()` method:
+
+[source,java]
+----
+client
+    .mutateWith(mockOpaqueToken()
+        .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
+    )
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-opaque-token-attributes]]
+==== Configuring Claims
+
+And while granted authorities are quite common across all of Spring Security, we also have attributes in the case of OAuth 2.0.
+
+Let's say, for example, that you've got a `user_id` attribute that indicates the user's id in your system.
+You might access it like so in a controller:
+
+[source,java]
+----
+@GetMapping("/endpoint")
+public Mono<String> foo(BearerTokenAuthentication authentication) {
+    String userId = (String) authentication.getTokenAttributes().get("user_id");
+    // ...
+}
+----
+
+In that case, you'd want to specify that attribute with the `attributes()` method:
+
+[source,java]
+----
+client
+    .mutateWith(mockOpaqueToken()
+        .attributes(attrs -> attrs.put("user_id", "1234"))
+    )
+    .get().uri("/endpoint").exchange();
+----
+
+[[webflux-testing-opaque-token-principal]]
+==== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects.
+
+One such is `principal(OAuth2AuthenticatedPrincipal)`, which you can use to configure the complete `OAuth2AuthenticatedPrincipal` instance that underlies the `BearerTokenAuthentication`
+
+It's handy if you:
+1. Have your own implementation of `OAuth2AuthenticatedPrincipal`, or
+2. Want to specify a different principal name
+
+For example, let's say that your authorization server sends the principal name in the `user_name` attribute instead of the `sub` attribute.
+In that case, you can configure an `OAuth2AuthenticatedPrincipal` by hand:
+
+[source,java]
+----
+Map<String, Object> attributes = Collections.singletonMap("user_name", "foo_user");
+OAuth2AuthenticatedPrincipal principal = new DefaultOAuth2AuthenticatedPrincipal(
+        (String) attributes.get("user_name"),
+        attributes,
+        AuthorityUtils.createAuthorityList("SCOPE_message:read"));
+
+client
+    .mutateWith(mockOpaqueToken().principal(principal))
+    .get().uri("/endpoint").exchange();
+----
+
+Note that as an alternative to using `mockOpaqueToken()` test support, you can also mock the `OpaqueTokenIntrospector` bean itself with a `@MockBean` annotation.

docs/manual/src/docs/asciidoc/_includes/servlet/test/mockmvc.adoc

@@ -240,257 +240,391 @@ will attempt to use HTTP Basic to authenticate a user with the username "user" a
 Authorization: Basic dXNlcjpwYXNzd29yZA==
 ----
 
-=== SecurityMockMvcRequestBuilders
+[[testing-oauth2]]
+==== Testing OAuth 2.0
 
-Spring MVC Test also provides a `RequestBuilder` interface that can be used to create the `MockHttpServletRequest` used in your test.
-Spring Security provides a few `RequestBuilder` implementations that can be used to make testing easier.
-In order to use Spring Security's `RequestBuilder` implementations ensure the following static import is used:
+When it comes to OAuth 2.0, the same principles covered earlier still apply: Ultimately, it depends on what your method under test is expecting to be in the `SecurityContextHolder`.
+
+For example, for a controller that looks like this:
 
 [source,java]
 ----
-import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.*;
+@GetMapping("/endpoint")
+public String foo(Principal user) {
+    return user.getName();
+}
 ----
 
-==== Testing Form Based Authentication
+There's nothing OAuth2-specific about it, so you will likely be able to simply <<test-method-withmockuser,use `@WithMockUser`>> and be fine.
 
-You can easily create a request to test a form based authentication using Spring Security's testing support.
-For example, the following will submit a POST to "/login" with the username "user", the password "password", and a valid CSRF token:
+But, in cases where your controllers are bound to some aspect of Spring Security's OAuth 2.0 support, like the following:
 
 [source,java]
 ----
-mvc
-	.perform(formLogin())
+@GetMapping("/endpoint")
+public String foo(@AuthenticationPrincipal OidcUser user) {
+    return user.getIdToken().getSubject();
+}
 ----
 
-It is easy to customize the request.
-For example, the following will submit a POST to "/auth" with the username "admin", the password "pass", and a valid CSRF token:
+then Spring Security's test support can come in handy.
 
-[source,java]
-----
-mvc
-	.perform(formLogin("/auth").user("admin").password("pass"))
-----
+[[testing-oidc-login]]
+==== Testing OIDC Login
 
-We can also customize the parameters names that the username and password are included on.
-For example, this is the above request modified to include the username on the HTTP parameter "u" and the password on the HTTP parameter "p".
+Testing the method above with Spring MVC Test would require simulating some kind of grant flow with an authorization server.
+Certainly this would be a daunting task, which is why Spring Security ships with support for removing this boilerplate.
+
+For example, we can tell Spring Security to include a default `OidcUser` using the `SecurityMockMvcRequestPostProcessors#oidcLogin` method, like so:
 
 [source,java]
 ----
 mvc
-	.perform(formLogin("/auth").user("u","admin").password("p","pass"))
+    .perform(get("/endpoint").with(oidcLogin()));
 ----
 
-[[testing-oidc-login]]
-==== Testing OIDC Login
-
-In order to make an authenticated request on an OAuth 2.0 client, you would need to simulate some kind of grant flow with an authorization server.
-However, Spring Security's OAuth 2.0 Client test support can help remove much of this boilerplate.
+What this will do is configure the associated `MockHttpServletRequest` with an `OidcUser` that includes a simple `OidcIdToken`, `OidcUserInfo`, and `Collection` of granted authorities.
 
-If your client uses OIDC to authenticate, then you can use the `oidcLogin()` `RequestPostProcessor` to configure a `MockMvc` request with an authenticated user.
-The simplest of these would look something like this:
+Specifically, it will include an `OidcIdToken` with a `sub` claim set to `user`:
 
-[source,java]
+[source,json]
 ----
-mvc.perform(get("/endpoint").with(oidcLogin()));
+assertThat(user.getIdToken().getClaim("sub")).isEqualTo("user");
 ----
 
-What this will do is create a mock `OidcUser`, passing it correctly through any authentication APIs so that it's available for your controllers and so on.
-It contains a mock `OidcUserInfo`, a mock `OidcIdToken`, and a mock `Collection` of granted authorities.
-Also, <<testing-oauth2-client,a mock `OAuth2AuthorizedClient`>> associated with the user is registered to an `HttpSessionOAuth2AuthorizedClientRepository`.
-
-By default, the user info has no claims, and the id token has the `sub` claim, like so:
+an `OidcUserInfo` with no claims set:
 
 [source,json]
 ----
-{
-    "sub" : "user"
-}
+assertThat(user.getUserInfo().getClaims()).isEmpty();
 ----
 
-And the resulting `OidcUser`, were it tested, would pass in the following way:
+and a `Collection` of authorities with just one authority, `SCOPE_read`:
 
-[source,java]
+[source,json]
 ----
-assertThat(user.getIdToken().getTokenValue()).isEqualTo("id-token");
-assertThat(user.getIdToken().getClaim("sub")).isEqualTo("user");
-assertThat(user.getUserInfo().getClaims()).isEmpty();
-GrantedAuthority authority = user.getAuthorities().iterator().next();
-assertThat(authority.getAuthority()).isEqualTo("SCOPE_read");
+assertThat(user.getAuthorities()).hasSize(1);
+assertThat(user.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));
 ----
 
-These values can, of course be configured.
+Spring Security does the necessary work to make sure that the `OidcUser` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+
+Further, it also links that `OidcUser` to a simple instance of `OAuth2AuthorizedClient` that it deposits into an `HttpSessionOAuth2AuthorizedClientRepository`.
+This can be handy if your tests <<testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>..
+
+[[testing-oidc-login-authorities]]
+===== Configuring Authorities
 
-Any claims can be configured with their corresponding methods:
+In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
+
+In this case, you can supply what granted authorities you need using the `authorities()` method:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint")
+mvc
+    .perform(get("/endpoint")
         .with(oidcLogin()
-                .idToken(idToken -> idToken.subject("my-subject"))
-                .userInfo(info -> info.firstName("Rob"))));
+            .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
+        )
+    );
 ----
 
+[[testing-oidc-login-claims]]
+===== Configuring Claims
+
+And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0.
+
+Let's say, for example, that you've got a `user_id` claim that indicates the user's id in your system.
+You might access it like so in a controller:
+
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(oidcLogin().idToken(idToken -> idToken.claims(claims -> claims.remove("scope")))));
+@GetMapping("/endpoint")
+public String foo(@AuthenticationPrincipal OidcUser oidcUser) {
+    String userId = oidcUser.getIdToken().getClaim("user_id");
+    // ...
+}
 ----
 
-By default, `oidcLogin()` adds a `SCOPE_read` `GrantedAuthority`.
-However, this can be overridden simply by providing the list of `GrantedAuthority` instances that you need for your test:
+In that case, you'd want to specify that claim with the `idToken()` method:
 
 [source,java]
 ----
 mvc
     .perform(get("/endpoint")
-        .with(oidcLogin().authorities(new SimpleGrantedAuthority("SCOPE_messages"))));
+        .with(oidcLogin()
+                .idToken(token -> token.claim("user_id", "1234"))
+        )
+    );
 ----
 
-Or, you can supply all detail via an instance of `OidcUser` like so:
+since `OidcUser` collects its claims from `OidcIdToken`.
+
+[[testing-oidc-login-user]]
+===== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
+
+* `userInfo(OidcUserInfo.Builder)` - For configuring the `OidcUserInfo` instance
+* `clientRegistration(ClientRegistration)` - For configuring the associated `OAuth2AuthorizedClient` with a given `ClientRegistration`
+* `oidcUser(OidcUser)` - For configuring the complete `OidcUser` instance
+
+That last one is handy if you:
+1. Have your own implementation of `OidcUser`, or
+2. Need to change the name attribute
+
+For example, let's say that your authorization server sends the principal name in the `user_name` claim instead of the `sub` claim.
+In that case, you can configure an `OidcUser` by hand:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(oidcLogin().oidcUser(new MyOidcUser())));
+OidcUser oidcUser = new DefaultOidcUser(
+        AuthorityUtils.createAuthorityList("SCOPE_message:read"),
+        Collections.singletonMap("user_name", "foo_user"),
+        "user_name");
+
+mvc
+    .perform(get("/endpoint")
+        .with(oidcLogin().oidcUser(oidcUser))
+    );
 ----
 
 [[testing-oauth2-login]]
 ==== Testing OAuth 2.0 Login
 
-Or, if your client uses OAuth 2.0 to authenticate, but not OIDC, then you can use the `oauth2Login()` `RequestPostProcessor` to configure a `MockMvc` request with an authenticated user.
-The simplest of these would look something like this:
+As with <<testing-oidc-login,testing OIDC login>>, testing OAuth 2.0 Login presents a similar challenge of mocking a grant flow.
+And because of that, Spring Security also has test support for non-OIDC use cases.
+
+Let's say that we've got a controller that gets the logged-in user as an `OAuth2User`:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint").with(oauth2Login()));
+@GetMapping("/endpoint")
+public String foo(@AuthenticationPrincipal OAuth2User oauth2User) {
+    return oauth2User.getAttribute("sub");
+}
 ----
 
-What this will do is create a mock `OAuth2User`, passing it correctly through any authentication APIs so that it's available for your controllers and so on.
-It contains a mock set of attributes and a mock `Collection` of granted authorities.
-Also, <<testing-oauth2-client,a mock `OAuth2AuthorizedClient`>> associated with the user is registered to an `HttpSessionOAuth2AuthorizedClientRepository`.
+In that case, we can tell Spring Security to include a default `OAuth2User` using the `SecurityMockMvcRequestPostProcessors#oauth2User` method, like so:
 
-By default, the set of attributes contains only `sub`:
+[source,java]
+----
+mvc
+    .perform(get("/endpoint").with(oauth2Login()));
+----
+
+What this will do is configure the associated `MockHttpServletRequest` with an `OAuth2User` that includes a simple `Map` of attributes and `Collection` of granted authorities.
+
+Specifically, it will include a `Map` with a key/value pair of `sub`/`user`:
 
 [source,json]
 ----
-{
-  "sub" : "user"
-}
+assertThat((String) user.getAttribute("sub")).isEqualTo("user");
 ----
 
-And the resulting `OAuth2User`, were it tested, would pass in the following way:
+and a `Collection` of authorities with just one authority, `SCOPE_read`:
 
-[source,java]
+[source,json]
 ----
-assertThat(user.getClaim("sub")).isEqualTo("user");
-GrantedAuthority authority = user.getAuthorities().iterator().next();
-assertThat(authority.getAuthority()).isEqualTo("SCOPE_read");
+assertThat(user.getAuthorities()).hasSize(1);
+assertThat(user.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));
 ----
 
-These values can, of course be configured.
+Spring Security does the necessary work to make sure that the `OAuth2User` instance is available for <<mvc-authentication-principal,the `@AuthenticationPrincipal` annotation>>.
+
+Further, it also links that `OAuth2User` to a simple instance of `OAuth2AuthorizedClient` that it deposits in an `HttpSessionOAuth2AuthorizedClientRepository`.
+This can be handy if your tests <<testing-oauth2-client,use the `@RegisteredOAuth2AuthorizedClient` annotation>>.
+
+[[testing-oauth2-login-authorities]]
+===== Configuring Authorities
 
-Any claims can be configured via the underlying `Map`:
+In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
+
+In this case, you can supply what granted authorities you need using the `authorities()` method:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint")
+mvc
+    .perform(get("/endpoint")
         .with(oauth2Login()
-                .attributes(attrs -> attrs.put("sub", "my-subject"))));
+            .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
+        )
+    );
 ----
 
+[[testing-oauth2-login-claims]]
+===== Configuring Claims
+
+And while granted authorities are quite common across all of Spring Security, we also have claims in the case of OAuth 2.0.
+
+Let's say, for example, that you've got a `user_id` attribute that indicates the user's id in your system.
+You might access it like so in a controller:
+
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(oauth2Login()
-                .attributes(attrs -> attrs.remove("some_claim"))));
+@GetMapping("/endpoint")
+public String foo(@AuthenticationPrincipal OAuth2User oauth2User) {
+    String userId = oauth2User.getAttribute("user_id");
+    // ...
+}
 ----
 
-By default, `oauth2User()` adds a `SCOPE_read` `GrantedAuthority`.
-However, this can be overridden simply by providing the list of `GrantedAuthority` instances that you need for your test:
+In that case, you'd want to specify that attribute with the `attributes()` method:
 
 [source,java]
 ----
 mvc
     .perform(get("/endpoint")
-        .with(oauth2Login().authorities(new SimpleGrantedAuthority("SCOPE_messages"))));
+        .with(oauth2Login()
+                .attributes(attrs -> attrs.put("user_id", "1234"))
+        )
+    );
 ----
 
-Or, you can supply all detail via an instance of `OAuth2User` like so:
+[[testing-oauth2-login-user]]
+===== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
+
+* `clientRegistration(ClientRegistration)` - For configuring the associated `OAuth2AuthorizedClient` with a given `ClientRegistration`
+* `oauth2User(OAuth2User)` - For configuring the complete `OAuth2User` instance
+
+That last one is handy if you:
+1. Have your own implementation of `OAuth2User`, or
+2. Need to change the name attribute
+
+For example, let's say that your authorization server sends the principal name in the `user_name` claim instead of the `sub` claim.
+In that case, you can configure an `OAuth2User` by hand:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(oauth2Login().oauth2User(new MyOAuth2User())));
+OAuth2User oauth2User = new DefaultOAuth2User(
+        AuthorityUtils.createAuthorityList("SCOPE_message:read"),
+        Collections.singletonMap("user_name", "foo_user"),
+        "user_name");
+
+mvc
+    .perform(get("/endpoint")
+        .with(oauth2Login().oauth2User(oauth2User))
+    );
 ----
 
 [[testing-oauth2-client]]
 ==== Testing OAuth 2.0 Clients
 
-Independent of how your user authenticates, there may be other OAuth 2.0 tokens that the request will need in order to communicate with resource servers, say in an integration test.
+Independent of how your user authenticates, you may have other tokens and client registrations that are in play for the request you are testing.
+For example, your controller may be relying on the client credentials grant to get a token that isn't associated with the user at all:
 
-If you need to express an OAuth 2.0 client in your test, then you can use the `oauth2Client()` `RequestPostProcessor` to configure a `MockMvc` request with an authorized client.
-The simplest of these would look something like this:
+[source,json]
+----
+@GetMapping("/endpoint")
+public String foo(@RegisteredOAuth2AuthorizedClient("my-app") OAuth2AuthorizedClient authorizedClient) {
+    return this.webClient.get()
+        .attributes(oauth2AuthorizedClient(authorizedClient))
+        .retrieve()
+        .bodyToMono(String.class)
+        .block();
+}
+----
+
+Simulating this handshake with the authorization server could be cumbersome.
+Instead, you can use `SecurityMockMvcRequestPostProcessor#oauth2Client` to add a `OAuth2AuthorizedClient` into an `HttpSessionOAuth2AuthorizedClientRepository`:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint").with(oauth2Client()));
+mvc
+    .perform(get("/endpoint").with(oauth2Client("my-app")));
 ----
 
-What this will do is create a mock `OAuth2AuthorizedClient`, passing it correctly through any authentication APIs.
-It contains a mock `ClientRegistration` and associated access token.
-It will register this `ClientRegistration` and access token in an `HttpSessionOAuth2AuthorizedClientRepository`.
-
-By default, the access token contains only the `scope` attribute:
+If your application isn't already using an `HttpSessionOAuth2AuthorizedClientRepository`, then you can supply one as a `@TestConfiguration`:
 
-[source,json]
+[source,java]
 ----
-{
-  "scope" : "read"
+@TestConfiguration
+static class AuthorizedClientConfig {
+    @Bean
+    OAuth2AuthorizedClientRepository authorizedClientRepository() {
+        return new HttpSessionOAuth2AuthorizedClientRepository();
+    }
 }
 ----
 
-And the resulting `OAuth2AuthorizedClient`, were it tested, would pass in the following way:
+What this will do is create an `OAuth2AuthorizedClient` that has a simple `ClientRegistration`, `OAuth2AccessToken`, and resource owner name.
 
-[source,java]
+Specifically, it will include a `ClientRegistration` with a client id of "test-client" and client secret of "test-secret":
+
+[source,json]
 ----
-assertThat(client.getClientRegistration().getRegistrationId()).isEqualTo("test");
-assertThat(client.getAccessToken().getTokenValue()).isEqualTo("access-token");
-assertThat(client.getPrincipalName()).isEqualTo("user");
+assertThat(authorizedClient.getClientRegistration().getClientId()).isEqualTo("test-client");
+assertThat(authorizedClient.getClientRegistration().getClientSecret()).isEqualTo("test-secret");
 ----
 
-These values can, of course, be configured.
+a resource owner name of "user":
 
-Any client details can be configured via the `ClientRegistration.Builder` like so:
-
-[source,java]
+[source,json]
 ----
-mvc.perform(get("/endpoint")
-        .with(oauth2Client()
-                .clientRegistration(client -> client.clientId("client-id"));
+assertThat(authorizedClient.getPrincipalName()).isEqualTo("user");
 ----
 
-To supply the corresponding token, invoke `accessToken()` like this:
+and an `OAuth2AccessToken` with just one scope, `read`:
 
-[source,java]
+[source,json]
 ----
-mvc.perform(get("/endpoint")
-        .with(oauth2Client()
-                .accessToken(new OAuth2AccessToken(BEARER, "my-value", issuedAt, expiresAt, scopes))));
+assertThat(authorizedClient.getAccessToken().getScopes()).hasSize(1);
+assertThat(authorizedClient.getAccessToken().getScopes()).containsExactly("read");
 ----
 
-===== `ClientRegistrationRepository` and `OAuth2AuthorizedClientRepository`
+Spring Security does the necessary work to make sure that the `OAuth2AuthorizedClient` instance is available in the associated `HttpSession`.
+That means that it can be retrieved from an `HttpSessionOAuth2AuthorizedClientRepository`.
 
-Under many circumstances, you will need to supply a registration id so that it can be looked up by exchange filter functions or `@RegisteredOAuth2AuthorizedClient` annotations.
-For this reason, `oauth2Client()` ships with a convenience method:
+[[testing-oauth2-client-scopes]]
+===== Configuring Scopes
+
+In many circumstances, the OAuth 2.0 access token comes with a set of scopes.
+If your controller inspects these, say like so:
+
+[source,json]
+----
+@GetMapping("/endpoint")
+public String foo(@RegisteredOAuth2AuthorizedClient("my-app") OAuth2AuthorizedClient authorizedClient) {
+    Set<String> scopes = authorizedClient.getAccessToken().getScopes();
+    if (scopes.contains("message:read")) {
+        return this.webClient.get()
+            .attributes(oauth2AuthorizedClient(authorizedClient))
+            .retrieve()
+            .bodyToMono(String.class)
+            .block();
+    }
+    // ...
+}
+----
+
+then you can configure the scope using the `accessToken()` method:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint").with(oauth2Client("facebook"));
+mvc
+    .perform(get("/endpoint")
+        .with(oauth2Client("my-app")
+            .accessToken(new OAuth2AccessToken(BEARER, "token", null, null, Collections.singleton("message:read"))))
+        )
+    );
 ----
 
-This, however, doesn't know about your application's `ClientRegistrationRepository`, so calling this does not look up your "facebook" client registration for you.
+[[testing-oauth2-client-registration]]
+===== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects:
+
+* `principalName(String)` - For configuring the resource owner name
+* `clientRegistration(Consumer<ClientRegistration.Builder>)` - For configuring the associated `ClientRegistration`
+* `clientRegistration(ClientRegistration)` - For configuring the complete `ClientRegistration`
+
+That last one is handy if you want to use a real `ClientRegistration`
 
-To configure a test with an actual `ClientRegistration` from your `ClientRegistrationRepository` you can do:
+For example, let's say that you are wanting to use one of your app's `ClientRegistration` definitions, as specified in your `application.yml`.
+
+In that case, your test can autowire the `ClientRegistrationRepository` and look up the one your test needs:
 
 [source,java]
 ----
@@ -499,25 +633,10 @@ ClientRegistrationRepository clientRegistrationRepository;
 
 // ...
 
-mvc.perform(get("/endpoint")
+mvc
+    .perform(get("/endpoint")
         .with(oauth2Client()
-                .clientRegistration(this.clientRegistrationRepository.findByRegistrationId("facebook"))));
-----
-
-Also, `oauth2Client()` doesn't know about your application's `OAuth2AuthorizedClientRepository`, which is what Spring Security uses to resolve `@RegisteredOAuth2AuthorizedClient` annotations.
-To make it available in your controllers, your app will need to be using an `HttpSessionOAuth2AuthorizedClientRepository` so that the token can be retrieved in a thread-safe way.
-
-You can isolate this configuration to your test via a test configuration like the following:
-
-[source,java]
-----
-@TestConfiguration
-static class TestAuthorizedClientRepositoryConfig {
-    @Bean
-    OAuth2AuthorizedClientRepository authorizedClientRepository() {
-        return new HttpSessionOAuth2AuthorizedClientRepository();
-    }
-}
+            .clientRegistration(this.clientRegistrationRepository.findByRegistrationId("facebook"))));
 ----
 
 [[testing-jwt]]
@@ -643,98 +762,161 @@ Note that as an alternative to these, you can also mock the `JwtDecoder` bean it
 [[testing-opaque-token]]
 ==== Testing Opaque Token Authentication
 
-Or, if your resource server is configured for opaque tokens, then this would mean that the bearer token needs to be registered with and verified against an authorization server.
-This can be just as distracting as creating a signed JWT.
+Similar to <<testing-jwt,JWTs>>, opaque tokens require an authorization server in order to verify their validity, which can make testing more difficult.
+To help with that, Spring Security has test support for opaque tokens.
 
-There are two simple ways that you can overcome this difficulty and allow your tests to focus on authorization and not on representing bearer tokens.
-Let's take a look:
+Let's say that we've got a controller that retrieves the authentication as a `BearerTokenAuthentication`:
 
-===== `opaqueToken()` `RequestPostProcessor`
+[source,java]
+----
+@GetMapping("/endpoint")
+public String foo(BearerTokenAuthentication authentication) {
+    return (String) authentication.getTokenAttributes("sub");
+}
+----
 
-The first way is via a `RequestPostProcessor`.
-The simplest of these would look something like this:
+In that case, we can tell Spring Security to include a default `BearerTokenAuthentication` using the `SecurityMockMvcRequestPostProcessors#opaqueToken` method, like so:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint").with(opaqueToken()));
+mvc
+    .perform(get("/endpoint").with(opaqueToken()));
 ----
 
-What this will do is create a mock `OAuth2AuthenticatedPrincipal`, passing it correctly through any authentication APIs so that it's available for your authorization mechanisms to verify.
+What this will do is configure the associated `MockHttpServletRequest` with a `BearerTokenAuthentication` that includes a simple `OAuth2AuthenticatedPrincipal`, `Map` of attributes, and `Collection` of granted authorities.
 
-By default, the set of attributes that it creates is like this:
+Specifically, it will include a `Map` with a key/value pair of `sub`/`user`:
 
 [source,json]
 ----
-{
-  "sub" : "user",
-  "scope" : "read"
-}
+assertThat((String) token.getTokenAttributes().get("sub")).isEqualTo("user");
+----
+
+and a `Collection` of authorities with just one authority, `SCOPE_read`:
+
+[source,json]
 ----
+assertThat(token.getAuthorities()).hasSize(1);
+assertThat(token.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));
+----
+
+Spring Security does the necessary work to make sure that the `BearerTokenAuthentication` instance is available for your controller methods.
 
-And the resulting `OAuth2AuthenticatedPrincipal`, were it tested, would pass in the following way:
+[[testing-opaque-token-authorities]]
+===== Configuring Authorities
+
+In many circumstances, your method is protected by filter or method security and needs your `Authentication` to have certain granted authorities to allow the request.
+
+In this case, you can supply what granted authorities you need using the `authorities()` method:
 
 [source,java]
 ----
-assertThat(principal.getAttribute("sub")).isEqualTo("user");
-GrantedAuthority authority = principal.getAuthorities().iterator().next();
-assertThat(authority.getAuthority()).isEqualTo("SCOPE_read");
+mvc
+    .perform(get("/endpoint")
+        .with(opaqueToken()
+            .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
+        )
+    );
 ----
 
-These values can, of course be configured.
+[[testing-opaque-token-attributes]]
+===== Configuring Claims
 
-Any attributes can be configured via an underlying `Map`:
+And while granted authorities are quite common across all of Spring Security, we also have attributes in the case of OAuth 2.0.
+
+Let's say, for example, that you've got a `user_id` attribute that indicates the user's id in your system.
+You might access it like so in a controller:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(opaqueToken().attributes(attrs -> attrs
-                .put("sub", "my-subject")
-                .put("my-claim", "my-value"))));
+@GetMapping("/endpoint")
+public String foo(BearerTokenAuthentication authentication) {
+    String userId = (String) authentication.getTokenAttributes().get("user_id");
+    // ...
+}
 ----
 
+In that case, you'd want to specify that attribute with the `attributes()` method:
+
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(opaqueToken().attributes(attrs -> attrs
-                .remove("scope"))));
+mvc
+    .perform(get("/endpoint")
+        .with(opaqueToken()
+                .attributes(attrs -> attrs.put("user_id", "1234"))
+        )
+    );
 ----
 
-The `scope` attribute is processed the same way here as it is in a normal bearer token request.
-However, this can be overridden simply by providing the list of `GrantedAuthority` instances that you need for your test:
+[[testing-opaque-token-principal]]
+===== Additional Configurations
+
+There are additional methods, too, for further configuring the authentication; it simply depends on what data your controller expects.
+
+One such is `principal(OAuth2AuthenticatedPrincipal)`, which you can use to configure the complete `OAuth2AuthenticatedPrincipal` instance that underlies the `BearerTokenAuthentication`
+
+It's handy if you:
+1. Have your own implementation of `OAuth2AuthenticatedPrincipal`, or
+2. Want to specify a different principal name
+
+For example, let's say that your authorization server sends the principal name in the `user_name` attribute instead of the `sub` attribute.
+In that case, you can configure an `OAuth2AuthenticatedPrincipal` by hand:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(opaqueToken().authorities(new SimpleGrantedAuthority("SCOPE_messages"))));
+Map<String, Object> attributes = Collections.singletonMap("user_name", "foo_user");
+OAuth2AuthenticatedPrincipal principal = new DefaultOAuth2AuthenticatedPrincipal(
+        (String) attributes.get("user_name"),
+        attributes,
+        AuthorityUtils.createAuthorityList("SCOPE_message:read"));
+
+mvc
+    .perform(get("/endpoint")
+        .with(opaqueToken().principal(principal))
+    );
 ----
 
-Or, you can supply all detail via an instance of `OAuth2AuthenticatedPrincipal` like so:
+Note that as an alternative to using `opaqueToken()` test support, you can also mock the `OpaqueTokenIntrospector` bean itself with a `@MockBean` annotation.
+
+=== SecurityMockMvcRequestBuilders
+
+Spring MVC Test also provides a `RequestBuilder` interface that can be used to create the `MockHttpServletRequest` used in your test.
+Spring Security provides a few `RequestBuilder` implementations that can be used to make testing easier.
+In order to use Spring Security's `RequestBuilder` implementations ensure the following static import is used:
 
 [source,java]
 ----
-mvc.perform(get("/endpoint")
-        .with(opaqueToken().principal(new MyAuthenticatedPrincipal())));
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.*;
 ----
 
-===== `authentication()` `RequestPostProcessor`
+==== Testing Form Based Authentication
 
-The second way is by using the `authentication()` `RequestPostProcessor`.
-Essentially, you can instantiate your own `BearerTokenAuthentication` and provide it in your test, like so:
+You can easily create a request to test a form based authentication using Spring Security's testing support.
+For example, the following will submit a POST to "/login" with the username "user", the password "password", and a valid CSRF token:
 
 [source,java]
 ----
-Map<String, Object> attributes = Collections.singletonMap("sub", "user");
-OAuth2AccessToken accessToken = new OAuth2AccessToken(BEARER, "token", null, null);
-Collection<GrantedAuthority> authorities = AuthorityUtils.createAuthorityList("SCOPE_read");
-OAuth2AuthenticatedPrincipal principal = new DefaultOAuth2AuthenticatedPrincipal(attributes, authorities);
+mvc
+	.perform(formLogin())
+----
 
-BearerTokenAuthentication token = new BearerTokenAuthentication(attributes, accessToken, authorities);
+It is easy to customize the request.
+For example, the following will submit a POST to "/auth" with the username "admin", the password "pass", and a valid CSRF token:
 
-mvc.perform(get("/endpoint")
-        .with(authentication(token)));
+[source,java]
+----
+mvc
+	.perform(formLogin("/auth").user("admin").password("pass"))
 ----
 
-Note that as an alternative to these, you can also mock the `OpaqueTokenIntrospector` bean itself with a `@MockBean` annotation.
+We can also customize the parameters names that the username and password are included on.
+For example, this is the above request modified to include the username on the HTTP parameter "u" and the password on the HTTP parameter "p".
+
+[source,java]
+----
+mvc
+	.perform(formLogin("/auth").user("u","admin").password("p","pass"))
+----
 
 [[test-logout]]
 ==== Testing Logout