Spring Security（三十五）：Part III. Testing

This section describes the testing support provided by Spring Security.

本节介绍Spring Security提供的测试支持。

To use the Spring Security test support, you must include spring-security-test-4.2.10.RELEASE.jar as a dependency of your project.

要使用Spring Security测试支持，必须将spring-security-test-4.2.10.RELEASE.jar作为项目的依赖项。

11. Testing Method Security

This section demonstrates how to use Spring Security’s Test support to test method based security. We first introduce a MessageService that requires the user to be authenticated in order to access it.

本节演示如何使用Spring Security的Test支持来测试基于安全性的方法。我们首先介绍一个MessageService，它要求用户进行身份验证才能访问它。

 

public class HelloMessageService implements MessageService {

	@PreAuthorize("authenticated")
	public String getMessage() {
		Authentication authentication = SecurityContextHolder.getContext()
															.getAuthentication();
		return "Hello " + authentication;
	}
}

The result of getMessage is a String saying "Hello" to the current Spring Security Authentication. An example of the output is displayed below.

getMessage的结果是一个String，表示当前Spring Security Authentication的“Hello”。输出的示例如下所示。

Hello org.springframework.security.authentication.UsernamePasswordAuthenticationToken@ca25360: Principal: org.springframework.security.core.userdetails.User@36ebcb: Username: user; Password: [PROTECTED]; Enabled: true; AccountNonExpired: true; credentialsNonExpired: true; AccountNonLocked: true; Granted Authorities: ROLE_USER; Credentials: [PROTECTED]; Authenticated: true; Details: null; Granted Authorities: ROLE_USER

11.1 Security Test Setup

Before we can use Spring Security Test support, we must perform some setup. An example can be seen below:

在我们使用Spring Security Test支持之前，我们必须执行一些设置。下面是一个例子：

 

@RunWith(SpringJUnit4ClassRunner.class) 1
@ContextConfiguration 2
public class WithMockUserTests {

This is a basic example of how to setup Spring Security Test. The highlights are:

这是如何设置Spring Security Test的基本示例。亮点是：

 

1、@RunWith instructs the spring-test module that it should create an ApplicationContext. This is no different than using the existing Spring Test support. For additional information, refer to the Spring Reference

@RunWith指示spring-test模块应该创建一个ApplicationContext。这与使用现有的Spring Test支持没什么不同。有关其他信息，请参阅Spring Reference

2、@ContextConfiguration instructs the spring-test the configuration to use to create the ApplicationContext. Since no configuration is specified, the default configuration locations will be tried. This is no different than using the existing Spring Test support. For additional information, refer to the Spring Reference

@ContextConfiguration指示spring-test用于创建ApplicationContext的配置。由于未指定任何配置，因此将尝试使用默认配置位置。这与使用现有的Spring Test支持没什么不同。有关其他信息，请参阅Spring Reference

 

Spring Security hooks into Spring Test support using the WithSecurityContextTestExecutionListener which will ensure our tests are ran with the correct user. It does this by populating the SecurityContextHolder prior to running our tests. After the test is done, it will clear out the SecurityContextHolder. If you only need Spring Security related support, you can replace @ContextConfiguration with @SecurityTestExecutionListeners.

Spring Security使用WithSecurityContextTestExecutionListener挂钩到Spring Test支持，这将确保我们的测试是使用正确的用户运行的。它通过在运行我们的测试之前填充SecurityContextHolder来实现。测试完成后，它将清除SecurityContextHolder。如果您只需要与Spring Security相关的支持，则可以使用@SecurityTestExecutionListeners替换@ContextConfiguration。

 

Remember we added the @PreAuthorize annotation to our HelloMessageService and so it requires an authenticated user to invoke it. If we ran the following test, we would expect the following test will pass:

请记住，我们将@PreAuthorize注释添加到HelloMessageService中，因此需要经过身份验证的用户才能调用它。如果我们运行以下测试，我们希望以下测试通过：

 

@Test(expected = AuthenticationCredentialsNotFoundException.class)
public void getMessageUnauthenticated() {
	messageService.getMessage();
}

11.2 @WithMockUser

The question is "How could we most easily run the test as a specific user?" The answer is to use @WithMockUser. The following test will be run as a user with the username "user", the password "password", and the roles "ROLE_USER".

问题是“作为特定用户，我们怎样才能最轻松地运行测试？”答案是使用@WithMockUser。以下测试将以用户名“user”，密码“password”和角色“ROLE_USER”的用户身份运行。

 

@Test
@WithMockUser
public void getMessageWithMockUser() {
String message = messageService.getMessage();
...
}

Specifically the following is true:

具体如下：

 

• The user with the username "user" does not have to exist since we are mocking the user
• 用户名为“user”的用户不必存在，因为我们正在模拟用户
• The Authentication that is populated in the SecurityContext is of type UsernamePasswordAuthenticationToken
• SecurityContext中填充的身份验证的类型为UsernamePasswordAuthenticationToken
• The principal on the Authentication is Spring Security’s User object
• 身份验证的主体是Spring Security的User对象
• The User will have the username of "user", the password "password", and a single GrantedAuthority named "ROLE_USER" is used.
• 用户将拥有“user”的用户名，密码“password”，并使用名为“ROLE_USER”的单个GrantedAuthority。

Our example is nice because we are able to leverage a lot of defaults. What if we wanted to run the test with a different username? The following test would run with the username "customUser". Again, the user does not need to actually exist.

我们的例子很好，因为我们能够利用很多默认值。如果我们想用不同的用户名运行测试怎么办？以下测试将使用用户名“customUser”运行。同样，用户不需要实际存在。

@Test
@WithMockUser("customUsername")
public void getMessageWithMockUserCustomUsername() {
	String message = messageService.getMessage();
...
}

We can also easily customize the roles. For example, this test will be invoked with the username "admin" and the roles "ROLE_USER" and "ROLE_ADMIN".

我们还可以轻松自定义角色。例如，将使用用户名“admin”和角色“ROLE_USER”和“ROLE_ADMIN”调用此测试。

@Test
@WithMockUser(username="admin",roles={"USER","ADMIN"})
public void getMessageWithMockUserCustomUser() {
	String message = messageService.getMessage();
	...
}

If we do not want the value to automatically be prefixed with ROLE_ we can leverage the authorities attribute. For example, this test will be invoked with the username "admin" and the authorities "USER" and "ADMIN".

如果我们不希望值自动以ROLE_为前缀，我们可以利用authority属性。例如，将使用用户名“admin”和权限“USER”和“ADMIN”调用此测试。

 

@Test
@WithMockUser(username = "admin", authorities = { "ADMIN", "USER" })
public void getMessageWithMockUserCustomAuthorities() {
	String message = messageService.getMessage();
	...
}

Of course it can be a bit tedious placing the annotation on every test method. Instead, we can place the annotation at the class level and every test will use the specified user. For example, the following would run every test with a user with the username "admin", the password "password", and the roles "ROLE_USER" and "ROLE_ADMIN".

当然，在每个测试方法上放置注释可能有点单调乏味。相反，我们可以将注释放在类级别，每个测试都将使用指定的用户。例如，以下内容将使用用户名为“admin”，密码为“password”以及角色“ROLE_USER”和“ROLE_ADMIN”的用户运行每个测试。

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
@WithMockUser(username="admin",roles={"USER","ADMIN"})
public class WithMockUserTests {

11.3 @WithAnonymousUser

Using @WithAnonymousUser allows running as an anonymous user. This is especially convenient when you wish to run most of your tests with a specific user, but want to run a few tests as an anonymous user. For example, the following will run withMockUser1 and withMockUser2 using @WithMockUser and anonymous as an anonymous user.

使用@WithAnonymousUser允许以匿名用户身份运行。当您希望与特定用户运行大多数测试但希望以匿名用户身份运行一些测试时，这尤其方便。例如，以下将使用@WithMockUser和匿名用户匿名用户运行withMockUser1和withMockUser2。

@RunWith(SpringJUnit4ClassRunner.class)
@WithMockUser
public class WithUserClassLevelAuthenticationTests {

	@Test
	public void withMockUser1() {
	}

	@Test
	public void withMockUser2() {
	}

	@Test
	@WithAnonymousUser
	public void anonymous() throws Exception {
		// override default to run as anonymous user
	}
}

11.4 @WithUserDetails

While @WithMockUser is a very convenient way to get started, it may not work in all instances. For example, it is common for applications to expect that the Authentication principal be of a specific type. This is done so that the application can refer to the principal as the custom type and reduce coupling on Spring Security.

虽然@WithMockUser是一种非常方便的入门方式，但它可能无法在所有实例中使用。例如，应用程序通常期望Authentication主体具有特定类型。这样做是为了使应用程序可以将主体称为自定义类型并减少Spring Security上的耦合。

 

The custom principal is often times returned by a custom UserDetailsService that returns an object that implements both UserDetails and the custom type. For situations like this, it is useful to create the test user using the custom UserDetailsService. That is exactly what @WithUserDetails does.

自定义主体通常由自定义UserDetailsS​​ervice返回，该自定义UserDetailsS​​ervice返回实现UserDetails和自定义类型的对象。对于这种情况，使用自定义UserDetailsS​​ervice创建测试用户很有用。这正是@WithUserDetails所做的。

 

Assuming we have a UserDetailsService exposed as a bean, the following test will be invoked with an Authentication of type UsernamePasswordAuthenticationToken and a principal that is returned from the UserDetailsService with the username of "user".

假设我们将UserDetailsS​​ervice公开为bean，将使用UsernamePasswordAuthenticationToken类型的Authentication和从UserDetailsS​​ervice返回的用户名为“user”的主体调用以下测试。

@Test
@WithUserDetails
public void getMessageWithUserDetails() {
	String message = messageService.getMessage();
	...
}

We can also customize the username used to lookup the user from our UserDetailsService. For example, this test would be executed with a principal that is returned from the UserDetailsService with the username of "customUsername".

我们还可以自定义用于从UserDetailsS​​ervice查找用户的用户名。例如，此测试将使用从UserDetailsS​​ervice返回的主体执行，其用户名为“customUsername”。

 

@Test
@WithUserDetails("customUsername")
public void getMessageWithUserDetailsCustomUsername() {
	String message = messageService.getMessage();
	...
}

We can also provide an explicit bean name to look up the UserDetailsService. For example, this test would look up the username of "customUsername" using the UserDetailsService with the bean name "myUserDetailsService".

我们还可以提供一个显式bean名称来查找UserDetailsS​​ervice。例如，此测试将使用具有bean名称“myUserDetailsS​​ervice”的UserDetailsS​​ervice查找“customUsername”的用户名。

@Test
@WithUserDetails(value="customUsername", userDetailsServiceBeanName="myUserDetailsService")
public void getMessageWithUserDetailsServiceBeanName() {
	String message = messageService.getMessage();
	...
}

Like @WithMockUser we can also place our annotation at the class level so that every test uses the same user. However unlike @WithMockUser, @WithUserDetailsrequires the user to exist.

与@WithMockUser一样，我们也可以将我们的注释放在类级别，以便每个测试都使用相同的用户。但是，与@WithMockUser不同，@ WithUserDetails要求用户存在。

11.5 @WithSecurityContext

We have seen that @WithMockUser is an excellent choice if we are not using a custom Authentication principal. Next we discovered that @WithUserDetails would allow us to use a custom UserDetailsService to create our Authentication principal but required the user to exist. We will now see an option that allows the most flexibility.

我们已经看到，如果我们不使用自定义身份验证主体，@ WinMockUser是一个很好的选择。接下来我们发现@WithUserDetails将允许我们使用自定义UserDetailsS​​ervice来创建我们的身份验证主体，但要求用户存在。我们现在将看到一个允许最大灵活性的选项。

 

We can create our own annotation that uses the @WithSecurityContext to create any SecurityContext we want. For example, we might create an annotation named @WithMockCustomUser as shown below:

我们可以创建自己的注释，使用@WithSecurityContext创建我们想要的任何SecurityContext。例如，我们可能会创建一个名为@WithMockCustomUser的注释，如下所示：

@Retention(RetentionPolicy.RUNTIME)
@WithSecurityContext(factory = WithMockCustomUserSecurityContextFactory.class)
public @interface WithMockCustomUser {

	String username() default "rob";

	String name() default "Rob Winch";
}

You can see that @WithMockCustomUser is annotated with the @WithSecurityContext annotation. This is what signals to Spring Security Test support that we intend to create a SecurityContext for the test. The @WithSecurityContext annotation requires we specify a SecurityContextFactory that will create a new SecurityContext given our @WithMockCustomUser annotation. You can find our WithMockCustomUserSecurityContextFactory implementation below:

您可以看到@WithMockCustomUser使用@WithSecurityContext注释进行注释。这是向Spring Security Test支持的信号，我们打算为测试创建SecurityContext。 @WithSecurityContext注释要求我们指定一个SecurityContextFactory，它将在给定@WithMockCustomUser注释的情况下创建一个新的SecurityContext。您可以在下面找到我们的WithMockCustomUserSecurityContextFactory实现：

public class WithMockCustomUserSecurityContextFactory
	implements WithSecurityContextFactory<WithMockCustomUser> {
	@Override
	public SecurityContext createSecurityContext(WithMockCustomUser customUser) {
		SecurityContext context = SecurityContextHolder.createEmptyContext();

		CustomUserDetails principal =
			new CustomUserDetails(customUser.name(), customUser.username());
		Authentication auth =
			new UsernamePasswordAuthenticationToken(principal, "password", principal.getAuthorities());
		context.setAuthentication(auth);
		return context;
	}
}

We can now annotate a test class or a test method with our new annotation and Spring Security’s WithSecurityContextTestExecutionListener will ensure that our SecurityContext is populated appropriately.

我们现在可以使用我们的新注释来注释测试类或测试方法，Spring Security的WithSecurityContextTestExecutionListener将确保我们的SecurityContext被适当地填充。

 

When creating your own WithSecurityContextFactory implementations, it is nice to know that they can be annotated with standard Spring annotations. For example, the WithUserDetailsSecurityContextFactory uses the @Autowired annotation to acquire the UserDetailsService:

在创建自己的WithSecurityContextFactory实现时，很高兴知道它们可以使用标准的Spring注释进行注释。例如，WithUserDetailsS​​ecurityContextFactory使用@Autowired批注获取UserDetailsS​​ervice：

 

final class WithUserDetailsSecurityContextFactory
	implements WithSecurityContextFactory<WithUserDetails> {

	private UserDetailsService userDetailsService;

	@Autowired
	public WithUserDetailsSecurityContextFactory(UserDetailsService userDetailsService) {
		this.userDetailsService = userDetailsService;
	}

	public SecurityContext createSecurityContext(WithUserDetails withUser) {
		String username = withUser.value();
		Assert.hasLength(username, "value() must be non-empty String");
		UserDetails principal = userDetailsService.loadUserByUsername(username);
		Authentication authentication = new UsernamePasswordAuthenticationToken(principal, principal.getPassword(), principal.getAuthorities());
		SecurityContext context = SecurityContextHolder.createEmptyContext();
		context.setAuthentication(authentication);
		return context;
	}
}

11.6 Test Meta Annotations

If you reuse the same user within your tests often, it is not ideal to have to repeatedly specify the attributes. For example, if there are many tests related to an administrative user with the username "admin" and the roles ROLE_USER and ROLE_ADMIN you would have to write:

如果经常在测试中重复使用同一个用户，则不必重复指定属性。例如，如果有许多与用户名为“admin”且角色为ROLE_USER和ROLE_ADMIN的管理用户相关的测试，则必须编写：

@WithMockUser(username="admin",roles={"USER","ADMIN"})

Rather than repeating this everywhere, we can use a meta annotation. For example, we could create a meta annotation named WithMockAdmin:

我们可以使用元注释，而不是在任何地方重复这一点。例如，我们可以创建一个名为WithMockAdmin的元注释：

@Retention(RetentionPolicy.RUNTIME)
@WithMockUser(value="rob",roles="ADMIN")
public @interface WithMockAdmin { }

Now we can use @WithMockAdmin in the same way as the more verbose @WithMockUser.

现在我们可以像更详细的@WithMockUser一样使用@WithMockAdmin。

Meta annotations work with any of the testing annotations described above. For example, this means we could create a meta annotation for @WithUserDetails("admin") as well.

元注释适用于上述任何测试注释。例如，这意味着我们也可以为@WithUserDetails（“admin”）创建元注释。