Skip to content

Commit 3766322

Browse files
jzheauxjzheaux
committed
Added OAuth 2.0 MockMvc Test Support Docs
Issue gh-8050
1 parent 2064214 commit 3766322

File tree

1 file changed

+338
-1
lines changed
  • docs/manual/src/docs/asciidoc/_includes/servlet/test

1 file changed

+338
-1
lines changed

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

Lines changed: 338 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -280,10 +280,251 @@ mvc
280280
.perform(formLogin("/auth").user("u","admin").password("p","pass"))
281281
----
282282

283+
[[testing-oidc-login]]
284+
==== Testing OIDC Login
283285

284-
==== Testing Bearer Authentication
286+
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.
287+
However, Spring Security's OAuth 2.0 Client test support can help remove much of this boilerplate.
288+
289+
If your client uses OIDC to authenticate, then you can use the `oidcLogin()` `RequestPostProcessor` to configure a `MockMvc` request with an authenticated user.
290+
The simplest of these would look something like this:
291+
292+
[source,java]
293+
----
294+
mvc.perform(get("/endpoint").with(oidcLogin()));
295+
----
296+
297+
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.
298+
It contains a mock `OidcUserInfo`, a mock `OidcIdToken`, and a mock `Collection` of granted authorities.
299+
Also, <<a mock `OAuth2AuthorizedClient`,testing-oauth2-client>> associated with the user is registered to an `HttpSessionOAuth2AuthorizedClientRepository`.
300+
301+
By default, the user info has no claims, and the id token has the `sub` claim, like so:
302+
303+
[source,json]
304+
----
305+
{
306+
"sub" : "user"
307+
}
308+
----
309+
310+
And the resulting `OidcUser`, were it tested, would pass in the following way:
311+
312+
[source,java]
313+
----
314+
assertThat(user.getIdToken().getTokenValue()).isEqualTo("id-token");
315+
assertThat(user.getIdToken().getClaim("sub")).isEqualTo("user");
316+
assertThat(user.getUserInfo().getClaims()).isEmpty();
317+
GrantedAuthority authority = user.getAuthorities().iterator().next();
318+
assertThat(authority.getAuthority()).isEqualTo("SCOPE_read");
319+
----
320+
321+
These values can, of course be configured.
322+
323+
Any claims can be configured with their corresponding methods:
324+
325+
[source,java]
326+
----
327+
mvc.perform(get("/endpoint")
328+
.with(oidcLogin()
329+
.idToken(idToken -> idToken.subject("my-subject"))
330+
.userInfo(info -> info.firstName("Rob"))));
331+
----
332+
333+
[source,java]
334+
----
335+
mvc.perform(get("/endpoint")
336+
.with(oidcLogin().idToken(idToken -> idToken.claims(claims -> claims.remove("scope")))));
337+
----
338+
339+
By default, `oidcLogin()` adds a `SCOPE_read` `GrantedAuthority`.
340+
However, this can be overridden simply by providing the list of `GrantedAuthority` instances that you need for your test:
341+
342+
[source,java]
343+
----
344+
mvc
345+
.perform(get("/endpoint")
346+
.with(oidcLogin().authorities(new SimpleGrantedAuthority("SCOPE_messages"))));
347+
----
348+
349+
Or, you can supply all detail via an instance of `OidcUser` like so:
350+
351+
[source,java]
352+
----
353+
mvc.perform(get("/endpoint")
354+
.with(oidcLogin().oidcUser(new MyOidcUser())));
355+
----
356+
357+
[[testing-oauth2-login]]
358+
==== Testing OAuth 2.0 Login
359+
360+
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.
361+
The simplest of these would look something like this:
362+
363+
[source,java]
364+
----
365+
mvc.perform(get("/endpoint").with(oauth2Login()));
366+
----
367+
368+
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.
369+
It contains a mock set of attributes and a mock `Collection` of granted authorities.
370+
Also, <<a mock `OAuth2AuthorizedClient`,testing-oauth2-client>> associated with the user is registered to an `HttpSessionOAuth2AuthorizedClientRepository`.
371+
372+
By default, the set of attributes contains only `sub`:
373+
374+
[source,json]
375+
----
376+
{
377+
"sub" : "user"
378+
}
379+
----
380+
381+
And the resulting `OAuth2User`, were it tested, would pass in the following way:
382+
383+
[source,java]
384+
----
385+
assertThat(user.getClaim("sub")).isEqualTo("user");
386+
GrantedAuthority authority = user.getAuthorities().iterator().next();
387+
assertThat(authority.getAuthority()).isEqualTo("SCOPE_read");
388+
----
389+
390+
These values can, of course be configured.
391+
392+
Any claims can be configured via the underlying `Map`:
393+
394+
[source,java]
395+
----
396+
mvc.perform(get("/endpoint")
397+
.with(oauth2Login()
398+
.attributes(attrs -> attrs.put("sub", "my-subject"))));
399+
----
400+
401+
[source,java]
402+
----
403+
mvc.perform(get("/endpoint")
404+
.with(oauth2Login()
405+
.attributes(attrs -> attrs.remove("some_claim"))));
406+
----
407+
408+
By default, `oauth2User()` adds a `SCOPE_read` `GrantedAuthority`.
409+
However, this can be overridden simply by providing the list of `GrantedAuthority` instances that you need for your test:
410+
411+
[source,java]
412+
----
413+
mvc
414+
.perform(get("/endpoint")
415+
.with(oauth2Login().authorities(new SimpleGrantedAuthority("SCOPE_messages"))));
416+
----
417+
418+
Or, you can supply all detail via an instance of `OAuth2User` like so:
419+
420+
[source,java]
421+
----
422+
mvc.perform(get("/endpoint")
423+
.with(oauth2Login().oauth2User(new MyOAuth2User())));
424+
----
425+
426+
[[testing-oauth2-client]]
427+
==== Testing OAuth 2.0 Clients
428+
429+
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.
430+
431+
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.
432+
The simplest of these would look something like this:
433+
434+
[source,java]
435+
----
436+
mvc.perform(get("/endpoint").with(oauth2Client()));
437+
----
438+
439+
What this will do is create a mock `OAuth2AuthorizedClient`, passing it correctly through any authentication APIs.
440+
It contains a mock `ClientRegistration` and associated access token.
441+
It will register this `ClientRegistration` and access token in an `HttpSessionOAuth2AuthorizedClientRepository`.
442+
443+
By default, the access token contains only the `scope` attribute:
444+
445+
[source,json]
446+
----
447+
{
448+
"scope" : "read"
449+
}
450+
----
451+
452+
And the resulting `OAuth2AuthorizedClient`, were it tested, would pass in the following way:
453+
454+
[source,java]
455+
----
456+
assertThat(client.getClientRegistration().getRegistrationId()).isEqualTo("test");
457+
assertThat(client.getAccessToken().getTokenValue()).isEqualTo("access-token");
458+
assertThat(client.getPrincipalName()).isEqualTo("user");
459+
----
460+
461+
These values can, of course, be configured.
462+
463+
Any client details can be configured via the `ClientRegistration.Builder` like so:
464+
465+
[source,java]
466+
----
467+
mvc.perform(get("/endpoint")
468+
.with(oauth2Client()
469+
.clientRegistration(client -> client.clientId("client-id"));
470+
----
471+
472+
To supply the corresponding token, invoke `accessToken()` like this:
473+
474+
[source,java]
475+
----
476+
mvc.perform(get("/endpoint")
477+
.with(oauth2Client()
478+
.accessToken(new OAuth2AccessToken(BEARER, "my-value", issuedAt, expiresAt, scopes))));
479+
----
480+
481+
===== `ClientRegistrationRepository` and `OAuth2AuthorizedClientRepository`
482+
483+
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.
484+
For this reason, `oauth2Client()` ships with a convenience method:
485+
486+
[source,java]
487+
----
488+
mvc.perform(get("/endpoint").with(oauth2Client("facebook"));
489+
----
490+
491+
This, however, doesn't know about your application's `ClientRegistrationRepository`, so calling this does not look up your "facebook" client registration for you.
492+
493+
To configure a test with an actual `ClientRegistration` from your `ClientRegistrationRepository` you can do:
494+
495+
[source,java]
496+
----
497+
@Autowired
498+
ClientRegistrationRepository clientRegistrationRepository;
499+
500+
// ...
501+
502+
mvc.perform(get("/endpoint")
503+
.with(oauth2Client()
504+
.clientRegistration(this.clientRegistrationRepository.findByRegistrationId("facebook"))));
505+
----
506+
507+
Also, `oauth2Client()` doesn't know about your application's `OAuth2AuthorizedClientRepository`, which is what Spring Security uses to resolve `@RegisteredOAuth2AuthorizedClient` annotations.
508+
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.
509+
510+
You can isolate this configuration to your test via a test configuration like the following:
511+
512+
[source,java]
513+
----
514+
@TestConfiguration
515+
static class TestAuthorizedClientRepositoryConfig {
516+
@Bean
517+
OAuth2AuthorizedClientRepository authorizedClientRepository() {
518+
return new HttpSessionOAuth2AuthorizedClientRepository();
519+
}
520+
}
521+
----
522+
523+
[[testing-jwt]]
524+
==== Testing JWT Authentication
285525

286526
In order to make an authorized request on a resource server, you need a bearer token.
527+
287528
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.
288529
All of this can be quite daunting, especially when this isn't the focus of your test.
289530

@@ -399,6 +640,102 @@ mvc
399640

400641
Note that as an alternative to these, you can also mock the `JwtDecoder` bean itself with a `@MockBean` annotation.
401642

643+
[[testing-opaque-token]]
644+
==== Testing Opaque Token Authentication
645+
646+
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.
647+
This can be just as distracting as creating a signed JWT.
648+
649+
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.
650+
Let's take a look:
651+
652+
===== `opaqueToken()` `RequestPostProcessor`
653+
654+
The first way is via a `RequestPostProcessor`.
655+
The simplest of these would look something like this:
656+
657+
[source,java]
658+
----
659+
mvc.perform(get("/endpoint").with(opaqueToken()));
660+
----
661+
662+
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.
663+
664+
By default, the set of attributes that it creates is like this:
665+
666+
[source,json]
667+
----
668+
{
669+
"sub" : "user",
670+
"scope" : "read"
671+
}
672+
----
673+
674+
And the resulting `OAuth2AuthenticatedPrincipal`, were it tested, would pass in the following way:
675+
676+
[source,java]
677+
----
678+
assertThat(principal.getAttribute("sub")).isEqualTo("user");
679+
GrantedAuthority authority = principal.getAuthorities().iterator().next();
680+
assertThat(authority.getAuthority()).isEqualTo("SCOPE_read");
681+
----
682+
683+
These values can, of course be configured.
684+
685+
Any attributes can be configured via an underlying `Map`:
686+
687+
[source,java]
688+
----
689+
mvc.perform(get("/endpoint")
690+
.with(opaqueToken().attributes(attrs -> attrs
691+
.put("sub", "my-subject")
692+
.put("my-claim", "my-value"))));
693+
----
694+
695+
[source,java]
696+
----
697+
mvc.perform(get("/endpoint")
698+
.with(opaqueToken().attributes(attrs -> attrs
699+
.remove("scope"))));
700+
----
701+
702+
The `scope` attribute is processed the same way here as it is in a normal bearer token request.
703+
However, this can be overridden simply by providing the list of `GrantedAuthority` instances that you need for your test:
704+
705+
[source,java]
706+
----
707+
mvc.perform(get("/endpoint")
708+
.with(opaqueToken().authorities(new SimpleGrantedAuthority("SCOPE_messages"))));
709+
----
710+
711+
Or, you can supply all detail via an instance of `OAuth2AuthenticatedPrincipal` like so:
712+
713+
[source,java]
714+
----
715+
mvc.perform(get("/endpoint")
716+
.with(opaqueToken().principal(new MyAuthenticatedPrincipal())));
717+
----
718+
719+
===== `authentication()` `RequestPostProcessor`
720+
721+
The second way is by using the `authentication()` `RequestPostProcessor`.
722+
Essentially, you can instantiate your own `BearerTokenAuthentication` and provide it in your test, like so:
723+
724+
[source,java]
725+
----
726+
Map<String, Object> attributes = Collections.singletonMap("sub", "user");
727+
OAuth2AccessToken accessToken = new OAuth2AccessToken(BEARER, "token", null, null);
728+
Collection<GrantedAuthority> authorities = AuthorityUtils.createAuthorityList("SCOPE_read");
729+
OAuth2AuthenticatedPrincipal principal = new DefaultOAuth2AuthenticatedPrincipal(attributes, authorities);
730+
731+
BearerTokenAuthentication token = new BearerTokenAuthentication(attributes, accessToken, authorities);
732+
733+
mvc.perform(get("/endpoint")
734+
.with(authentication(token)));
735+
----
736+
737+
Note that as an alternative to these, you can also mock the `OpaqueTokenIntrospector` bean itself with a `@MockBean` annotation.
738+
402739
[[test-logout]]
403740
==== Testing Logout
404741

0 commit comments

Comments
 (0)