Spring MVC Test Integration

Spring Security provides comprehensive integration with Spring MVC Test

Setting Up MockMvc and Spring Security

In order to use Spring Security with Spring MVC Test it is necessary to add the Spring Security FilterChainProxy as a Filter. It is also necessary to add Spring Security’s TestSecurityContextHolderPostProcessor to support Running as a User in Spring MVC Test with Annotations. This can be done using Spring Security’s SecurityMockMvcConfigurers.springSecurity(). For example:

Spring Security’s testing support requires spring-test-4.1.3.RELEASE or greater.

Java

import static org.springframework.security.test.web.servlet.setup.SecurityMockMvcConfigurers.*;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = SecurityConfig.class)
@WebAppConfiguration
public class CsrfShowcaseTests {

	@Autowired
	private WebApplicationContext context;

	private MockMvc mvc;

	@Before
	public void setup() {
		mvc = MockMvcBuilders
				.webAppContextSetup(context)
				.apply(springSecurity()) (1)
				.build();
	}

...

Kotlin

@RunWith(SpringJUnit4ClassRunner::class)
@ContextConfiguration(classes = [SecurityConfig::class])
@WebAppConfiguration
class CsrfShowcaseTests {

    @Autowired
    private lateinit var context: WebApplicationContext

    private var mvc: MockMvc? = null

    @Before
    fun setup() {
        mvc = MockMvcBuilders
            .webAppContextSetup(context)
            .apply<DefaultMockMvcBuilder>(springSecurity()) (1)
            .build()
    }
// ...

1	`SecurityMockMvcConfigurers.springSecurity()` will perform all of the initial setup we need to integrate Spring Security with Spring MVC Test

SecurityMockMvcRequestPostProcessors

Spring MVC Test provides a convenient interface called a RequestPostProcessor that can be used to modify a request. Spring Security provides a number of RequestPostProcessor implementations that make testing easier. In order to use Spring Security’s RequestPostProcessor implementations ensure the following static import is used:

Java

import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.*;

Kotlin

import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.*

Testing with CSRF Protection

When testing any non-safe HTTP methods and using Spring Security’s CSRF protection, you must be sure to include a valid CSRF Token in the request. To specify a valid CSRF token as a request parameter using the following:

Java

mvc
	.perform(post("/").with(csrf()))

Kotlin

mvc.post("/") {
    with(csrf())
}

If you like you can include CSRF token in the header instead:

Java

mvc
	.perform(post("/").with(csrf().asHeader()))

Kotlin

mvc.post("/") {
    with(csrf().asHeader())
}

You can also test providing an invalid CSRF token using the following:

Java

mvc
	.perform(post("/").with(csrf().useInvalidToken()))

Kotlin

mvc.post("/") {
    with(csrf().useInvalidToken())
}

Running a Test as a User in Spring MVC Test

It is often desirable to run tests as a specific user. There are two simple ways of populating the user:

Running as a User in Spring MVC Test with RequestPostProcessor
Running as a User in Spring MVC Test with Annotations

Running as a User in Spring MVC Test with RequestPostProcessor

There are a number of options available to associate a user to the current HttpServletRequest. For example, the following will run as a user (which does not need to exist) with the username "user", the password "password", and the role "ROLE_USER":

The support works by associating the user to the HttpServletRequest. To associate the request to the SecurityContextHolder you need to ensure that the SecurityContextPersistenceFilter is associated with the MockMvc instance. A few ways to do this are:

Invoking apply(springSecurity())
Adding Spring Security’s FilterChainProxy to MockMvc
Manually adding SecurityContextPersistenceFilter to the MockMvc instance may make sense when using MockMvcBuilders.standaloneSetup

Java

mvc
	.perform(get("/").with(user("user")))

Kotlin

mvc.get("/") {
    with(user("user"))
}

You can easily make customizations. For example, the following will run as a user (which does not need to exist) with the username "admin", the password "pass", and the roles "ROLE_USER" and "ROLE_ADMIN".

Java

mvc
	.perform(get("/admin").with(user("admin").password("pass").roles("USER","ADMIN")))

Kotlin

mvc.get("/admin") {
    with(user("admin").password("pass").roles("USER","ADMIN"))
}

If you have a custom UserDetails that you would like to use, you can easily specify that as well. For example, the following will use the specified UserDetails (which does not need to exist) to run with a UsernamePasswordAuthenticationToken that has a principal of the specified UserDetails:

Java

mvc
	.perform(get("/").with(user(userDetails)))

Kotlin

mvc.get("/") {
    with(user(userDetails))
}

You can run as anonymous user using the following:

Java

mvc
	.perform(get("/").with(anonymous()))

Kotlin

mvc.get("/") {
    with(anonymous())
}

This is especially useful if you are running with a default user and wish to process a few requests as an anonymous user.

If you want a custom Authentication (which does not need to exist) you can do so using the following:

Java

mvc
	.perform(get("/").with(authentication(authentication)))

Kotlin

mvc.get("/") {
    with(authentication(authentication))
}

You can even customize the SecurityContext using the following:

Java

mvc
	.perform(get("/").with(securityContext(securityContext)))

Kotlin

mvc.get("/") {
    with(securityContext(securityContext))
}

We can also ensure to run as a specific user for every request by using MockMvcBuilders's default request. For example, the following will run as a user (which does not need to exist) with the username "admin", the password "password", and the role "ROLE_ADMIN":

Java

mvc = MockMvcBuilders
		.webAppContextSetup(context)
		.defaultRequest(get("/").with(user("user").roles("ADMIN")))
		.apply(springSecurity())
		.build();

Kotlin

mvc = MockMvcBuilders
    .webAppContextSetup(context)
    .defaultRequest<DefaultMockMvcBuilder>(get("/").with(user("user").roles("ADMIN")))
    .apply<DefaultMockMvcBuilder>(springSecurity())
    .build()

If you find you are using the same user in many of your tests, it is recommended to move the user to a method. For example, you can specify the following in your own class named CustomSecurityMockMvcRequestPostProcessors:

Java

public static RequestPostProcessor rob() {
	return user("rob").roles("ADMIN");
}

Kotlin

fun rob(): RequestPostProcessor {
    return user("rob").roles("ADMIN")
}

Now you can perform a static import on SecurityMockMvcRequestPostProcessors and use that within your tests:

Java

import static sample.CustomSecurityMockMvcRequestPostProcessors.*;

...

mvc
	.perform(get("/").with(rob()))

Kotlin

import sample.CustomSecurityMockMvcRequestPostProcessors.*

//...

mvc.get("/") {
    with(rob())
}

Running as a User in Spring MVC Test with Annotations

As an alternative to using a RequestPostProcessor to create your user, you can use annotations described in [Testing Method Security]. For example, the following will run the test with the user with username "user", password "password", and role "ROLE_USER":

Java

@Test
@WithMockUser
public void requestProtectedUrlWithUser() throws Exception {
mvc
		.perform(get("/"))
		...
}

Kotlin

@Test
@WithMockUser
fun requestProtectedUrlWithUser() {
    mvc
        .get("/")
        // ...
}

Alternatively, the following will run the test with the user with username "user", password "password", and role "ROLE_ADMIN":

Java

@Test
@WithMockUser(roles="ADMIN")
public void requestProtectedUrlWithUser() throws Exception {
mvc
		.perform(get("/"))
		...
}

Kotlin

@Test
@WithMockUser(roles = ["ADMIN"])
fun requestProtectedUrlWithUser() {
    mvc
        .get("/")
        // ...
}

Testing HTTP Basic Authentication

While it has always been possible to authenticate with HTTP Basic, it was a bit tedious to remember the header name, format, and encode the values. Now this can be done using Spring Security’s httpBasic RequestPostProcessor. For example, the snippet below:

Java

mvc
	.perform(get("/").with(httpBasic("user","password")))

Kotlin

mvc.get("/") {
    with(httpBasic("user","password"))
}

will attempt to use HTTP Basic to authenticate a user with the username "user" and the password "password" by ensuring the following header is populated on the HTTP Request:

Authorization: Basic dXNlcjpwYXNzd29yZA==

Testing OAuth 2.0

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:

Java

@GetMapping("/endpoint")
public String foo(Principal user) {
    return user.getName();
}

Kotlin

@GetMapping("/endpoint")
fun foo(user: Principal): String {
    return user.name
}

There’s nothing OAuth2-specific about it, so you will likely be able to simply 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:

Java

@GetMapping("/endpoint")
public String foo(@AuthenticationPrincipal OidcUser user) {
    return user.getIdToken().getSubject();
}

Kotlin

@GetMapping("/endpoint")
fun foo(@AuthenticationPrincipal user: OidcUser): String {
    return user.idToken.subject
}

then Spring Security’s test support can come in handy.

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:

Java

mvc
    .perform(get("/endpoint").with(oidcLogin()));

Kotlin

mvc.get("/endpoint") {
    with(oidcLogin())
}

What this will do is configure the associated MockHttpServletRequest 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:

Java

assertThat(user.getIdToken().getClaim("sub")).isEqualTo("user");

Kotlin

assertThat(user.idToken.getClaim<String>("sub")).isEqualTo("user")

an OidcUserInfo with no claims set:

Java

assertThat(user.getUserInfo().getClaims()).isEmpty();

Kotlin

assertThat(user.userInfo.claims).isEmpty()

and a Collection of authorities with just one authority, SCOPE_read:

Java

assertThat(user.getAuthorities()).hasSize(1);
assertThat(user.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));

Kotlin

assertThat(user.authorities).hasSize(1)
assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read"))

Spring Security does the necessary work to make sure that the OidcUser instance is available for the @AuthenticationPrincipal annotation.

Further, it also links that OidcUser to a simple instance of OAuth2AuthorizedClient that it deposits into an mock OAuth2AuthorizedClientRepository. This can be handy if your tests use the @RegisteredOAuth2AuthorizedClient annotation..

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:

Java

mvc
    .perform(get("/endpoint")
        .with(oidcLogin()
            .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
        )
    );

Kotlin

mvc.get("/endpoint") {
    with(oidcLogin()
        .authorities(SimpleGrantedAuthority("SCOPE_message:read"))
    )
}

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:

Java

@GetMapping("/endpoint")
public String foo(@AuthenticationPrincipal OidcUser oidcUser) {
    String userId = oidcUser.getIdToken().getClaim("user_id");
    // ...
}

Kotlin

@GetMapping("/endpoint")
fun foo(@AuthenticationPrincipal oidcUser: OidcUser): String {
    val userId = oidcUser.idToken.getClaim<String>("user_id")
    // ...
}

In that case, you’d want to specify that claim with the idToken() method:

Java

mvc
    .perform(get("/endpoint")
        .with(oidcLogin()
                .idToken(token -> token.claim("user_id", "1234"))
        )
    );

Kotlin

mvc.get("/endpoint") {
    with(oidcLogin()
        .idToken {
            it.claim("user_id", "1234")
        }
    )
}

since OidcUser collects its claims from OidcIdToken.

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:

Java

OidcUser oidcUser = new DefaultOidcUser(
        AuthorityUtils.createAuthorityList("SCOPE_message:read"),
        OidcIdToken.withTokenValue("id-token").claim("user_name", "foo_user").build(),
        "user_name");

mvc
    .perform(get("/endpoint")
        .with(oidcLogin().oidcUser(oidcUser))
    );

Kotlin

val oidcUser: OidcUser = DefaultOidcUser(
    AuthorityUtils.createAuthorityList("SCOPE_message:read"),
    OidcIdToken.withTokenValue("id-token").claim("user_name", "foo_user").build(),
    "user_name"
)

mvc.get("/endpoint") {
    with(oidcLogin().oidcUser(oidcUser))
}

As with 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:

Java

@GetMapping("/endpoint")
public String foo(@AuthenticationPrincipal OAuth2User oauth2User) {
    return oauth2User.getAttribute("sub");
}

Kotlin

@GetMapping("/endpoint")
fun foo(@AuthenticationPrincipal oauth2User: OAuth2User): String? {
    return oauth2User.getAttribute("sub")
}

In that case, we can tell Spring Security to include a default OAuth2User using the SecurityMockMvcRequestPostProcessors#oauth2User method, like so:

Java

mvc
    .perform(get("/endpoint").with(oauth2Login()));

Kotlin

mvc.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:

Java

assertThat((String) user.getAttribute("sub")).isEqualTo("user");

Kotlin

assertThat(user.getAttribute<String>("sub")).isEqualTo("user")

and a Collection of authorities with just one authority, SCOPE_read:

Java

assertThat(user.getAuthorities()).hasSize(1);
assertThat(user.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));

Kotlin

assertThat(user.authorities).hasSize(1)
assertThat(user.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read"))

Spring Security does the necessary work to make sure that the OAuth2User instance is available for the @AuthenticationPrincipal annotation.

Further, it also links that OAuth2User to a simple instance of OAuth2AuthorizedClient that it deposits in a mock OAuth2AuthorizedClientRepository. This can be handy if your tests use the @RegisteredOAuth2AuthorizedClient annotation.

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:

Java

mvc
    .perform(get("/endpoint")
        .with(oauth2Login()
            .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
        )
    );

Kotlin

mvc.get("/endpoint") {
    with(oauth2Login()
        .authorities(SimpleGrantedAuthority("SCOPE_message:read"))
    )
}

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:

Java

@GetMapping("/endpoint")
public String foo(@AuthenticationPrincipal OAuth2User oauth2User) {
    String userId = oauth2User.getAttribute("user_id");
    // ...
}

Kotlin

@GetMapping("/endpoint")
fun foo(@AuthenticationPrincipal oauth2User: OAuth2User): String {
    val userId = oauth2User.getAttribute<String>("user_id")
    // ...
}

In that case, you’d want to specify that attribute with the attributes() method:

Java

mvc
    .perform(get("/endpoint")
        .with(oauth2Login()
                .attributes(attrs -> attrs.put("user_id", "1234"))
        )
    );

Kotlin

mvc.get("/endpoint") {
    with(oauth2Login()
        .attributes { attrs -> attrs["user_id"] = "1234" }
    )
}

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:

Java

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))
    );

Kotlin

val oauth2User: OAuth2User = DefaultOAuth2User(
    AuthorityUtils.createAuthorityList("SCOPE_message:read"),
    mapOf(Pair("user_name", "foo_user")),
    "user_name"
)

mvc.get("/endpoint") {
    with(oauth2Login().oauth2User(oauth2User))
}

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:

Java

@GetMapping("/endpoint")
public String foo(@RegisteredOAuth2AuthorizedClient("my-app") OAuth2AuthorizedClient authorizedClient) {
    return this.webClient.get()
        .attributes(oauth2AuthorizedClient(authorizedClient))
        .retrieve()
        .bodyToMono(String.class)
        .block();
}

Kotlin

@GetMapping("/endpoint")
fun foo(@RegisteredOAuth2AuthorizedClient("my-app") authorizedClient: OAuth2AuthorizedClient?): String? {
    return this.webClient.get()
        .attributes(oauth2AuthorizedClient(authorizedClient))
        .retrieve()
        .bodyToMono(String::class.java)
        .block()
}

Simulating this handshake with the authorization server could be cumbersome. Instead, you can use SecurityMockMvcRequestPostProcessor#oauth2Client to add a OAuth2AuthorizedClient into a mock OAuth2AuthorizedClientRepository:

Java

mvc
    .perform(get("/endpoint").with(oauth2Client("my-app")));

Kotlin

mvc.get("/endpoint") {
    with(
        oauth2Client("my-app")
    )
}

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":

Java

assertThat(authorizedClient.getClientRegistration().getClientId()).isEqualTo("test-client");
assertThat(authorizedClient.getClientRegistration().getClientSecret()).isEqualTo("test-secret");

Kotlin

assertThat(authorizedClient.clientRegistration.clientId).isEqualTo("test-client")
assertThat(authorizedClient.clientRegistration.clientSecret).isEqualTo("test-secret")

a resource owner name of "user":

Java

assertThat(authorizedClient.getPrincipalName()).isEqualTo("user");

Kotlin

assertThat(authorizedClient.principalName).isEqualTo("user")

and an OAuth2AccessToken with just one scope, read:

Java

assertThat(authorizedClient.getAccessToken().getScopes()).hasSize(1);
assertThat(authorizedClient.getAccessToken().getScopes()).containsExactly("read");

Kotlin

assertThat(authorizedClient.accessToken.scopes).hasSize(1)
assertThat(authorizedClient.accessToken.scopes).containsExactly("read")

The client can then be retrieved as normal using @RegisteredOAuth2AuthorizedClient in a controller method.

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:

Java

@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();
    }
    // ...
}

Kotlin

@GetMapping("/endpoint")
fun foo(@RegisteredOAuth2AuthorizedClient("my-app") authorizedClient: OAuth2AuthorizedClient): String? {
    val scopes = authorizedClient.accessToken.scopes
    if (scopes.contains("message:read")) {
        return webClient.get()
            .attributes(oauth2AuthorizedClient(authorizedClient))
            .retrieve()
            .bodyToMono(String::class.java)
            .block()
    }
    // ...
}

then you can configure the scope using the accessToken() method:

Java

mvc
    .perform(get("/endpoint")
        .with(oauth2Client("my-app")
            .accessToken(new OAuth2AccessToken(BEARER, "token", null, null, Collections.singleton("message:read"))))
        )
    );

Kotlin

mvc.get("/endpoint") {
    with(oauth2Client("my-app")
            .accessToken(OAuth2AccessToken(BEARER, "token", null, null, Collections.singleton("message:read")))
    )
}

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 ClientRegistrationRepository and look up the one your test needs:

Java

@Autowired
ClientRegistrationRepository clientRegistrationRepository;

// ...

mvc
    .perform(get("/endpoint")
        .with(oauth2Client()
            .clientRegistration(this.clientRegistrationRepository.findByRegistrationId("facebook"))));

Kotlin

@Autowired
lateinit var clientRegistrationRepository: ClientRegistrationRepository

// ...

mvc.get("/endpoint") {
    with(oauth2Client("my-app")
        .clientRegistration(clientRegistrationRepository.findByRegistrationId("facebook"))
    )
}

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. All of this can be quite daunting, especially when this isn’t the focus of your test.

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:

`jwt() RequestPostProcessor`

The first way is via a RequestPostProcessor. The simplest of these would look something like this:

Java

mvc
    .perform(get("/endpoint").with(jwt()));

Kotlin

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.

By default, the JWT that it creates has the following characteristics:

{
  "headers" : { "alg" : "none" },
  "claims" : {
    "sub" : "user",
    "scope" : "read"
  }
}

And the resulting Jwt, were it tested, would pass in the following way:

Java

assertThat(jwt.getTokenValue()).isEqualTo("token");
assertThat(jwt.getHeaders().get("alg")).isEqualTo("none");
assertThat(jwt.getSubject()).isEqualTo("sub");

Kotlin

assertThat(jwt.tokenValue).isEqualTo("token")
assertThat(jwt.headers["alg"]).isEqualTo("none")
assertThat(jwt.subject).isEqualTo("sub")

These values can, of course be configured.

Any headers or claims can be configured with their corresponding methods:

Java

mvc
    .perform(get("/endpoint")
        .with(jwt().jwt(jwt -> jwt.header("kid", "one").claim("iss", "https://idp.example.org"))));

Kotlin

mvc.get("/endpoint") {
    with(
        jwt().jwt { jwt -> jwt.header("kid", "one").claim("iss", "https://idp.example.org") }
    )
}

Java

mvc
    .perform(get("/endpoint")
        .with(jwt().jwt(jwt -> jwt.claims(claims -> claims.remove("scope")))));

Kotlin

mvc.get("/endpoint") {
    with(
        jwt().jwt { jwt -> jwt.claims { claims -> claims.remove("scope") } }
    )
}

The scope and scp claims are processed the same way here as they are 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:

Java

mvc
    .perform(get("/endpoint")
        .with(jwt().authorities(new SimpleGrantedAuthority("SCOPE_messages"))));

Kotlin

mvc.get("/endpoint") {
    with(
        jwt().authorities(SimpleGrantedAuthority("SCOPE_messages"))
    )
}

Or, if you have a custom Jwt to Collection<GrantedAuthority> converter, you can also use that to derive the authorities:

Java

mvc
    .perform(get("/endpoint")
        .with(jwt().authorities(new MyConverter())));

Kotlin

mvc.get("/endpoint") {
    with(
        jwt().authorities(MyConverter())
    )
}

You can also specify a complete Jwt, for which Jwt.Builder comes quite handy:

Java

Jwt jwt = Jwt.withTokenValue("token")
    .header("alg", "none")
    .claim("sub", "user")
    .claim("scope", "read")
    .build();

mvc
    .perform(get("/endpoint")
        .with(jwt().jwt(jwt)));

Kotlin

val jwt: Jwt = Jwt.withTokenValue("token")
    .header("alg", "none")
    .claim("sub", "user")
    .claim("scope", "read")
    .build()

mvc.get("/endpoint") {
    with(
        jwt().jwt(jwt)
    )
}

`authentication()` `RequestPostProcessor`

The second way is by using the authentication() RequestPostProcessor. Essentially, you can instantiate your own JwtAuthenticationToken and provide it in your test, like so:

Java

Jwt jwt = Jwt.withTokenValue("token")
    .header("alg", "none")
    .claim("sub", "user")
    .build();
Collection<GrantedAuthority> authorities = AuthorityUtils.createAuthorityList("SCOPE_read");
JwtAuthenticationToken token = new JwtAuthenticationToken(jwt, authorities);

mvc
    .perform(get("/endpoint")
        .with(authentication(token)));

Kotlin

val jwt = Jwt.withTokenValue("token")
    .header("alg", "none")
    .claim("sub", "user")
    .build()
val authorities: Collection<GrantedAuthority> = AuthorityUtils.createAuthorityList("SCOPE_read")
val token = JwtAuthenticationToken(jwt, authorities)

mvc.get("/endpoint") {
    with(
        authentication(token)
    )
}

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

Testing Opaque Token Authentication

Similar to 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:

Java

@GetMapping("/endpoint")
public String foo(BearerTokenAuthentication authentication) {
    return (String) authentication.getTokenAttributes().get("sub");
}

Kotlin

@GetMapping("/endpoint")
fun foo(authentication: BearerTokenAuthentication): String {
    return authentication.tokenAttributes["sub"] as String
}

In that case, we can tell Spring Security to include a default BearerTokenAuthentication using the SecurityMockMvcRequestPostProcessors#opaqueToken method, like so:

Java

mvc
    .perform(get("/endpoint").with(opaqueToken()));

Kotlin

mvc.get("/endpoint") {
    with(opaqueToken())
}

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:

Java

assertThat((String) token.getTokenAttributes().get("sub")).isEqualTo("user");

Kotlin

assertThat(token.tokenAttributes["sub"] as String).isEqualTo("user")

and a Collection of authorities with just one authority, SCOPE_read:

Java

assertThat(token.getAuthorities()).hasSize(1);
assertThat(token.getAuthorities()).containsExactly(new SimpleGrantedAuthority("SCOPE_read"));

Kotlin

assertThat(token.authorities).hasSize(1)
assertThat(token.authorities).containsExactly(SimpleGrantedAuthority("SCOPE_read"))

Spring Security does the necessary work to make sure that the BearerTokenAuthentication instance is available for your controller methods.

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:

Java

mvc
    .perform(get("/endpoint")
        .with(opaqueToken()
            .authorities(new SimpleGrantedAuthority("SCOPE_message:read"))
        )
    );

Kotlin

mvc.get("/endpoint") {
    with(opaqueToken()
        .authorities(SimpleGrantedAuthority("SCOPE_message:read"))
    )
}

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:

Java

@GetMapping("/endpoint")
public String foo(BearerTokenAuthentication authentication) {
    String userId = (String) authentication.getTokenAttributes().get("user_id");
    // ...
}

Kotlin

@GetMapping("/endpoint")
fun foo(authentication: BearerTokenAuthentication): String {
    val userId = authentication.tokenAttributes["user_id"] as String
    // ...
}

In that case, you’d want to specify that attribute with the attributes() method:

Java

mvc
    .perform(get("/endpoint")
        .with(opaqueToken()
                .attributes(attrs -> attrs.put("user_id", "1234"))
        )
    );

Kotlin

mvc.get("/endpoint") {
    with(opaqueToken()
        .attributes { attrs -> attrs["user_id"] = "1234" }
    )
}

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:

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"));

mvc
    .perform(get("/endpoint")
        .with(opaqueToken().principal(principal))
    );

Kotlin

val attributes: Map<String, Any> = Collections.singletonMap("user_name", "foo_user")
val principal: OAuth2AuthenticatedPrincipal = DefaultOAuth2AuthenticatedPrincipal(
    attributes["user_name"] as String?,
    attributes,
    AuthorityUtils.createAuthorityList("SCOPE_message:read")
)

mvc.get("/endpoint") {
    with(opaqueToken().principal(principal))
}

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:

Java

import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.*;

Kotlin

import org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestBuilders.*

Testing Form Based Authentication

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:

Java

mvc
	.perform(formLogin())

Kotlin

mvc
	.perform(formLogin())

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:

Java

mvc
	.perform(formLogin("/auth").user("admin").password("pass"))

Kotlin

mvc
    .perform(formLogin("/auth").user("admin").password("pass"))

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".

Java

mvc
	.perform(formLogin("/auth").user("u","admin").password("p","pass"))

Kotlin

mvc
    .perform(formLogin("/auth").user("u","admin").password("p","pass"))

Testing Logout

While fairly trivial using standard Spring MVC Test, you can use Spring Security’s testing support to make testing log out easier. For example, the following will submit a POST to "/logout" with a valid CSRF token:

Java

mvc
	.perform(logout())

Kotlin

mvc
    .perform(logout())

You can also customize the URL to post to. For example, the snippet below will submit a POST to "/signout" with a valid CSRF token:

Java

mvc
	.perform(logout("/signout"))

Kotlin

mvc
	.perform(logout("/signout"))

SecurityMockMvcResultMatchers

At times it is desirable to make various security related assertions about a request. To accommodate this need, Spring Security Test support implements Spring MVC Test’s ResultMatcher interface. In order to use Spring Security’s ResultMatcher implementations ensure the following static import is used:

Java

import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultMatchers.*;

Kotlin

import org.springframework.security.test.web.servlet.response.SecurityMockMvcResultMatchers.*

Unauthenticated Assertion

At times it may be valuable to assert that there is no authenticated user associated with the result of a MockMvc invocation. For example, you might want to test submitting an invalid username and password and verify that no user is authenticated. You can easily do this with Spring Security’s testing support using something like the following:

Java

mvc
	.perform(formLogin().password("invalid"))
	.andExpect(unauthenticated());

Kotlin

mvc
    .perform(formLogin().password("invalid"))
    .andExpect { unauthenticated() }

Authenticated Assertion

It is often times that we must assert that an authenticated user exists. For example, we may want to verify that we authenticated successfully. We could verify that a form based login was successful with the following snippet of code:

Java

mvc
	.perform(formLogin())
	.andExpect(authenticated());

Kotlin

mvc
    .perform(formLogin())
    .andExpect { authenticated() }

If we wanted to assert the roles of the user, we could refine our previous code as shown below:

Java

mvc
	.perform(formLogin().user("admin"))
	.andExpect(authenticated().withRoles("USER","ADMIN"));

Kotlin

mvc
    .perform(formLogin())
    .andExpect { authenticated().withRoles("USER","ADMIN") }

Alternatively, we could verify the username:

Java

mvc
	.perform(formLogin().user("admin"))
	.andExpect(authenticated().withUsername("admin"));

Kotlin

mvc
    .perform(formLogin().user("admin"))
    .andExpect { authenticated().withUsername("admin") }

We can also combine the assertions:

Java

mvc
	.perform(formLogin().user("admin"))
	.andExpect(authenticated().withUsername("admin").withRoles("USER", "ADMIN"));

Kotlin

mvc
    .perform(formLogin().user("admin"))
    .andExpect { authenticated().withUsername("admin").withRoles("USER", "ADMIN") }

We can also make arbitrary assertions on the authentication

Java

mvc
	.perform(formLogin())
	.andExpect(authenticated().withAuthentication(auth ->
		assertThat(auth).isInstanceOf(UsernamePasswordAuthenticationToken.class)));

Kotlin

mvc
    .perform(formLogin())
    .andExpect {
        authenticated().withAuthentication { auth ->
            assertThat(auth).isInstanceOf(UsernamePasswordAuthenticationToken::class.java) }
        }
    }

SecurityMockMvcResultHandlers

Spring Security provides a few ResultHandlers implementations. In order to use Spring Security’s ResultHandlers implementations ensure the following static import is used:

import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultHandlers.*;

Exporting the SecurityContext

Often times we want to query a repository to see if some MockMvc request actually persisted in the database. In some cases our repository query uses the Spring Data Integration to filter the results based on current user’s username or any other property. Let’s see an example:

A repository interface:

private interface MessageRepository extends JpaRepository<Message, Long> {
	@Query("SELECT m.content FROM Message m WHERE m.sentBy = ?#{ principal?.name }")
	List<String> findAllUserMessages();
}

Our test scenario:

mvc
	.perform(post("/message")
		.content("New Message")
		.contentType(MediaType.TEXT_PLAIN)
	)
	.andExpect(status().isOk());

List<String> userMessages = messageRepository.findAllUserMessages();
assertThat(userMessages).hasSize(1);

This test won’t pass because after our request finishes, the SecurityContextHolder will be cleared out by the filter chain. We can then export the TestSecurityContextHolder to our SecurityContextHolder and use it as we want:

mvc
	.perform(post("/message")
		.content("New Message")
		.contentType(MediaType.TEXT_PLAIN)
	)
	.andDo(exportTestSecurityContext())
	.andExpect(status().isOk());

List<String> userMessages = messageRepository.findAllUserMessages();
assertThat(userMessages).hasSize(1);

Remember to clear the SecurityContextHolder between your tests, or it may leak amongst them

Spring MVC Test Integration

Setting Up MockMvc and Spring Security

SecurityMockMvcRequestPostProcessors

Testing with CSRF Protection

Running a Test as a User in Spring MVC Test

Running as a User in Spring MVC Test with RequestPostProcessor

Running as a User in Spring MVC Test with Annotations

Testing HTTP Basic Authentication

Testing OAuth 2.0

Testing OIDC Login

Configuring Authorities

Configuring Claims

Additional Configurations

Testing OAuth 2.0 Login

Configuring Authorities

Configuring Claims

Additional Configurations

Testing OAuth 2.0 Clients

Configuring Scopes

Additional Configurations

Testing JWT Authentication

jwt() RequestPostProcessor

authentication() RequestPostProcessor

Testing Opaque Token Authentication

Configuring Authorities

Configuring Claims

Additional Configurations

SecurityMockMvcRequestBuilders

Testing Form Based Authentication

Testing Logout

SecurityMockMvcResultMatchers

Unauthenticated Assertion

Authenticated Assertion

SecurityMockMvcResultHandlers

Exporting the SecurityContext

`jwt() RequestPostProcessor`

`authentication()` `RequestPostProcessor`