1. Overview
In this tutorial, we’ll focus on creating a custom security expression with Spring Security.
Sometimes, the expressions available in the framework are simply not expressive enough. And, in these cases, it’s relatively simple to built up a new expression that is semantically richer than the existing ones.
We’ll first discuss how to create a custom PermissionEvaluator, then a fully custom expression – and finally how to override one of the built-in security expression.
2. A User Entity
First, let’s prepare the foundation for creating the new security expressions.
Let’s have a look at our User entity – which has a Privileges and an Organization:
@Entity
public class User{
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;
@Column(nullable = false, unique = true)
private String username;
private String password;
@ManyToMany(fetch = FetchType.EAGER)
@JoinTable(name = "users_privileges",
joinColumns =
@JoinColumn(name = "user_id", referencedColumnName = "id"),
inverseJoinColumns =
@JoinColumn(name = "privilege_id", referencedColumnName = "id"))
private Set<Privilege> privileges;
@ManyToOne(fetch = FetchType.EAGER)
@JoinColumn(name = "organization_id", referencedColumnName = "id")
private Organization organization;
// standard getters and setters
}
And here is our simple Privilege:
@Entity
public class Privilege {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;
@Column(nullable = false, unique = true)
private String name;
// standard getters and setters
}
And our Organization:
@Entity
public class Organization {
@Id
@GeneratedValue(strategy = GenerationType.AUTO)
private Long id;
@Column(nullable = false, unique = true)
private String name;
// standard setters and getters
}
Finally – we’ll use a simpler custom Principal:
public class MyUserPrincipal implements UserDetails {
private User user;
public MyUserPrincipal(User user) {
this.user = user;
}
@Override
public String getUsername() {
return user.getUsername();
}
@Override
public String getPassword() {
return user.getPassword();
}
@Override
public Collection<? extends GrantedAuthority> getAuthorities() {
List<GrantedAuthority> authorities = new ArrayList<GrantedAuthority>();
for (Privilege privilege : user.getPrivileges()) {
authorities.add(new SimpleGrantedAuthority(privilege.getName()));
}
return authorities;
}
...
}
With all of these classes ready, we’re going to use our custom Principal in a basic UserDetailsService implementation:
@Service
public class MyUserDetailsService implements UserDetailsService {
@Autowired
private UserRepository userRepository;
@Override
public UserDetails loadUserByUsername(String username) {
User user = userRepository.findByUsername(username);
if (user == null) {
throw new UsernameNotFoundException(username);
}
return new MyUserPrincipal(user);
}
}
As you can see, there’s nothing complicated about these relationships – the user has one or more privileges, and each user belong to one organization.
3. Data Setup
Next – let’s initialize our database with simple test data:
@Component
public class SetupData {
@Autowired
private UserRepository userRepository;
@Autowired
private PrivilegeRepository privilegeRepository;
@Autowired
private OrganizationRepository organizationRepository;
@PostConstruct
public void init() {
initPrivileges();
initOrganizations();
initUsers();
}
}
Here is our init methods:
private void initPrivileges() {
Privilege privilege1 = new Privilege("FOO_READ_PRIVILEGE");
privilegeRepository.save(privilege1);
Privilege privilege2 = new Privilege("FOO_WRITE_PRIVILEGE");
privilegeRepository.save(privilege2);
}
private void initOrganizations() {
Organization org1 = new Organization("FirstOrg");
organizationRepository.save(org1);
Organization org2 = new Organization("SecondOrg");
organizationRepository.save(org2);
}
private void initUsers() {
Privilege privilege1 = privilegeRepository.findByName("FOO_READ_PRIVILEGE");
Privilege privilege2 = privilegeRepository.findByName("FOO_WRITE_PRIVILEGE");
User user1 = new User();
user1.setUsername("john");
user1.setPassword("123");
user1.setPrivileges(new HashSet<Privilege>(Arrays.asList(privilege1)));
user1.setOrganization(organizationRepository.findByName("FirstOrg"));
userRepository.save(user1);
User user2 = new User();
user2.setUsername("tom");
user2.setPassword("111");
user2.setPrivileges(new HashSet<Privilege>(Arrays.asList(privilege1, privilege2)));
user2.setOrganization(organizationRepository.findByName("SecondOrg"));
userRepository.save(user2);
}
Note that:
- User “john” has only FOO_READ_PRIVILEGE
- User “tom” has both FOO_READ_PRIVILEGE and FOO_WRITE_PRIVILEGE
4. A Custom Permission Evaluator
At this point we’re ready to start implementing our new expression – through a new, custom permission evaluator.
We are going to use the user’s privileges to secure our methods – but instead of using hard coded privilege names, we want to reach a more open, flexible implementation.
Let’s get started.
4.1. PermissionEvaluator
In order to create our own custom permission evaluator we need to implement the PermissionEvaluator interface:
public class CustomPermissionEvaluator implements PermissionEvaluator {
@Override
public boolean hasPermission(
Authentication auth, Object targetDomainObject, Object permission) {
if ((auth == null) || (targetDomainObject == null) || !(permission instanceof String)){
return false;
}
String targetType = targetDomainObject.getClass().getSimpleName().toUpperCase();
return hasPrivilege(auth, targetType, permission.toString().toUpperCase());
}
@Override
public boolean hasPermission(
Authentication auth, Serializable targetId, String targetType, Object permission) {
if ((auth == null) || (targetType == null) || !(permission instanceof String)) {
return false;
}
return hasPrivilege(auth, targetType.toUpperCase(),
permission.toString().toUpperCase());
}
}
Here is our hasPrivilege() method:
private boolean hasPrivilege(Authentication auth, String targetType, String permission) {
for (GrantedAuthority grantedAuth : auth.getAuthorities()) {
if (grantedAuth.getAuthority().startsWith(targetType) &&
grantedAuth.getAuthority().contains(permission)) {
return true;
}
}
return false;
}
We now have a new security expression available and ready to be used: hasPermission.
And so, instead of using the more hardcoded version:
@PostAuthorize("hasAuthority('FOO_READ_PRIVILEGE')")
We can use use:
@PostAuthorize("hasPermission(returnObject, 'read')")
or
@PreAuthorize("hasPermission(#id, 'Foo', 'read')")
Note: #id refers to method parameter and ‘Foo‘ refers to target object type.
4.2. Method Security Configuration
It’s not enough to define the CustomPermissionEvaluator – we also need to use it in our method security configuration:
@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class MethodSecurityConfig extends GlobalMethodSecurityConfiguration {
@Override
protected MethodSecurityExpressionHandler createExpressionHandler() {
DefaultMethodSecurityExpressionHandler expressionHandler =
new DefaultMethodSecurityExpressionHandler();
expressionHandler.setPermissionEvaluator(new CustomPermissionEvaluator());
return expressionHandler;
}
}
4.3. Example in Practice
Let’s now start making use of the new expression – in a few simple controller methods:
@Controller
public class MainController {
@PostAuthorize("hasPermission(returnObject, 'read')")
@GetMapping("/foos/{id}")
@ResponseBody
public Foo findById(@PathVariable long id) {
return new Foo("Sample");
}
@PreAuthorize("hasPermission(#foo, 'write')")
@PostMapping("/foos")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
public Foo create(@RequestBody Foo foo) {
return foo;
}
}
And there we go – we’re all set and using the new expression in practice.
4.4. The Live Test
Let’s now write a simple live tests – hitting the API and making sure everything’s in working order:
@Test
public void givenUserWithReadPrivilegeAndHasPermission_whenGetFooById_thenOK() {
Response response = givenAuth("john", "123").get("http://localhost:8082/foos/1");
assertEquals(200, response.getStatusCode());
assertTrue(response.asString().contains("id"));
}
@Test
public void givenUserWithNoWritePrivilegeAndHasPermission_whenPostFoo_thenForbidden() {
Response response = givenAuth("john", "123").contentType(MediaType.APPLICATION_JSON_VALUE)
.body(new Foo("sample"))
.post("http://localhost:8082/foos");
assertEquals(403, response.getStatusCode());
}
@Test
public void givenUserWithWritePrivilegeAndHasPermission_whenPostFoo_thenOk() {
Response response = givenAuth("tom", "111").contentType(MediaType.APPLICATION_JSON_VALUE)
.body(new Foo("sample"))
.post("http://localhost:8082/foos");
assertEquals(201, response.getStatusCode());
assertTrue(response.asString().contains("id"));
}
And here is our givenAuth() method:
private RequestSpecification givenAuth(String username, String password) {
FormAuthConfig formAuthConfig =
new FormAuthConfig("http://localhost:8082/login", "username", "password");
return RestAssured.given().auth().form(username, password, formAuthConfig);
}
5. A New Security Expression
With the previous solution, we were able to define and use the hasPermission expression – which can be quite useful.
However, we’re still somewhat limited here by the name and semantics of the expression itself.
And so, in this section, we’re going to go full custom – and we’re going to implement a security expression called isMember() – checking if the principal is a member of a Organization.
5.1. Custom Method Security Expression
In order to create this new custom expression, we need start by implementing the root note where the evaluation of all security expressions starts:
public class CustomMethodSecurityExpressionRoot
extends SecurityExpressionRoot implements MethodSecurityExpressionOperations {
public CustomMethodSecurityExpressionRoot(Authentication authentication) {
super(authentication);
}
public boolean isMember(Long OrganizationId) {
User user = ((MyUserPrincipal) this.getPrincipal()).getUser();
return user.getOrganization().getId().longValue() == OrganizationId.longValue();
}
...
}
Now how we provided this new operation right in the root note here; isMember() is used to check if current user is a member in given Organization.
Also note how we extended the SecurityExpressionRoot to include the built-in expressions as well.
5.2. Custom Expression Handler
Next, we need to inject our CustomMethodSecurityExpressionRoot in our expression handler:
public class CustomMethodSecurityExpressionHandler
extends DefaultMethodSecurityExpressionHandler {
private AuthenticationTrustResolver trustResolver =
new AuthenticationTrustResolverImpl();
@Override
protected MethodSecurityExpressionOperations createSecurityExpressionRoot(
Authentication authentication, MethodInvocation invocation) {
CustomMethodSecurityExpressionRoot root =
new CustomMethodSecurityExpressionRoot(authentication);
root.setPermissionEvaluator(getPermissionEvaluator());
root.setTrustResolver(this.trustResolver);
root.setRoleHierarchy(getRoleHierarchy());
return root;
}
}
5.3. Method Security Configuration
Now, we need to use our CustomMethodSecurityExpressionHandler in the method security configuration:
@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class MethodSecurityConfig extends GlobalMethodSecurityConfiguration {
@Override
protected MethodSecurityExpressionHandler createExpressionHandler() {
CustomMethodSecurityExpressionHandler expressionHandler =
new CustomMethodSecurityExpressionHandler();
expressionHandler.setPermissionEvaluator(new CustomPermissionEvaluator());
return expressionHandler;
}
}
5.4. Using the New Expression
Here is a simple example to secure our controller method using isMember():
@PreAuthorize("isMember(#id)")
@GetMapping("/organizations/{id}")
@ResponseBody
public Organization findOrgById(@PathVariable long id) {
return organizationRepository.findOne(id);
}
5.5. Live Test
Finally, here is a simple live test for user “john“:
@Test
public void givenUserMemberInOrganization_whenGetOrganization_thenOK() {
Response response = givenAuth("john", "123").get("http://localhost:8082/organizations/1");
assertEquals(200, response.getStatusCode());
assertTrue(response.asString().contains("id"));
}
@Test
public void givenUserMemberNotInOrganization_whenGetOrganization_thenForbidden() {
Response response = givenAuth("john", "123").get("http://localhost:8082/organizations/2");
assertEquals(403, response.getStatusCode());
}
6. Disable a Built-in Security Expression
Finally, let’s see how to override a built-in security expression – we’ll discuss disabling hasAuthority().
6.1. Custom Security Expression Root
We’ll start similarly by writing our own SecurityExpressionRoot – mainly because the built-in methods are final and so we can’t override them:
public class MySecurityExpressionRoot implements MethodSecurityExpressionOperations {
public MySecurityExpressionRoot(Authentication authentication) {
if (authentication == null) {
throw new IllegalArgumentException("Authentication object cannot be null");
}
this.authentication = authentication;
}
@Override
public final boolean hasAuthority(String authority) {
throw new RuntimeException("method hasAuthority() not allowed");
}
...
}
After defining this root note, we’ll have to inject it into the expression handler and then wire that handler into our configuration – just as we did above in Section 5.
6.2. Example – Using the Expression
Now, if we want to use hasAuthority() to secure methods – as follows, it will throw RuntimeException when we try to access method:
@PreAuthorize("hasAuthority('FOO_READ_PRIVILEGE')")
@GetMapping("/foos")
@ResponseBody
public Foo findFooByName(@RequestParam String name) {
return new Foo(name);
}
6.3. Live Test
Finally, here is our simple test:
@Test
public void givenDisabledSecurityExpression_whenGetFooByName_thenError() {
Response response = givenAuth("john", "123").get("http://localhost:8082/foos?name=sample");
assertEquals(500, response.getStatusCode());
}
7. Conclusion
In this guide, we did a deep-dive into the various ways we can implement a custom security expression in Spring Security, if the existing ones aren’t enough.
And, as always, the full source code can be found over on GitHub.