From 53573abc851b997947564e9856e81b9026737160 Mon Sep 17 00:00:00 2001 From: Houssam El Mansouri Date: Tue, 23 Sep 2025 13:20:32 +0100 Subject: [PATCH] Align JWT Testing Documentation Signed-off-by: Houssam El Mansouri --- .../ROOT/pages/reactive/test/web/oauth2.adoc | 55 +++++++++++++++++-- .../pages/servlet/test/mockmvc/oauth2.adoc | 55 +++++++++++++++++-- 2 files changed, 102 insertions(+), 8 deletions(-) diff --git a/docs/modules/ROOT/pages/reactive/test/web/oauth2.adoc b/docs/modules/ROOT/pages/reactive/test/web/oauth2.adoc index c37d85e189a..23a1897c17d 100644 --- a/docs/modules/ROOT/pages/reactive/test/web/oauth2.adoc +++ b/docs/modules/ROOT/pages/reactive/test/web/oauth2.adoc @@ -787,11 +787,58 @@ client ====== [[webflux-testing-jwt]] -== Testing JWT Authentication +== Testing OAuth 2.0 Resource Servers with JWT -To make an authorized request on a resource server, you need a bearer token. -If your resource server is configured for JWTs, the bearer token needs to be signed and then encoded according to the JWT specification. -All of this can be quite daunting, especially when this is not the focus of your test. +Similar to <>, JWTs 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 JWTs. + +Suppose you have a controller that retrieves the authentication as a `Jwt`: + +[tabs] +====== +Java:: ++ +[source,java,role="primary"] +---- +@GetMapping("/endpoint") +public Mono foo(@AuthenticationPrincipal Jwt jwt) { + return Mono.just(jwt.getClaimAsString("sub")); +} +---- + +Kotlin:: ++ +[source,kotlin,role="secondary"] +---- +@GetMapping("/endpoint") +fun foo(@AuthenticationPrincipal jwt: Jwt): Mono { + return Mono.just(jwt.getClaimAsString("sub")) +} +---- +====== + +In that case, you can tell Spring Security to include a default `Jwt` by using the `SecurityMockServerConfigurers#mockJwt` method: + +[tabs] +====== +Java:: ++ +[source,java,role="primary"] +---- +client + .mutateWith(mockJwt()).get().uri("/endpoint").exchange(); +---- + +Kotlin:: ++ +[source,kotlin,role="secondary"] +---- +client + .mutateWith(mockJwt()).get().uri("/endpoint").exchange() +---- +====== + +This example creates a mock `Jwt` and passes it through any authentication APIs so that it is available for your authorization mechanisms to verify. Fortunately, there are a number of simple ways in which you can overcome this difficulty and let your tests focus on authorization and not on representing bearer tokens. We look at two of them in the next two subsections. diff --git a/docs/modules/ROOT/pages/servlet/test/mockmvc/oauth2.adoc b/docs/modules/ROOT/pages/servlet/test/mockmvc/oauth2.adoc index 8c4db2fb0bd..c3b24306af3 100644 --- a/docs/modules/ROOT/pages/servlet/test/mockmvc/oauth2.adoc +++ b/docs/modules/ROOT/pages/servlet/test/mockmvc/oauth2.adoc @@ -790,12 +790,59 @@ mvc.get("/endpoint") { ====== [[testing-jwt]] -== Testing JWT Authentication +== Testing OAuth 2.0 Resource Servers with JWT -In order to make an authorized request on a resource server, you need a bearer token. +Similar to <>, JWTs 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 JWTs. -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. -All of this can be quite daunting, especially when this isn't the focus of your test. +Let's say that we've got a controller that retrieves the authentication as a `Jwt`: + +[tabs] +====== +Java:: ++ +[source,java,role="primary"] +---- +@GetMapping("/endpoint") +public String foo(@AuthenticationPrincipal Jwt jwt) { + return jwt.getClaimAsString("sub"); +} +---- + +Kotlin:: ++ +[source,kotlin,role="secondary"] +---- +@GetMapping("/endpoint") +fun foo(@AuthenticationPrincipal jwt: Jwt): String { + return jwt.getClaimAsString("sub") +} +---- +====== + +In that case, we can tell Spring Security to include a default `Jwt` using the `jwt` xref:servlet/test/mockmvc/request-post-processors.adoc[`RequestPostProcessor`], like so: + +[tabs] +====== +Java:: ++ +[source,java,role="primary"] +---- +mvc + .perform(get("/endpoint").with(jwt())); +---- + +Kotlin:: ++ +[source,kotlin,role="secondary"] +---- +mvc.get("/endpoint") { + with(jwt()) +} +---- +====== + +What this will do is create a mock `Jwt`, passing it correctly through any authentication APIs so that it's available for your authorization mechanisms to verify. Fortunately, there are a number of simple ways that you can overcome this difficulty and allow your tests to focus on authorization and not on representing bearer tokens. We'll look at two of them now: