User Authorization #

Diego comes with some convenient tools to cover the 90% use cases for user authorization. At the time of writing, these tools are geared toward the MVC style of application, but similar functionality can be replicated in Express-style applications with the use of Filters.

The Authorization Flow #

The authorization flow comprises 3 basic steps:

1. Set an Authorization Provider;
2. Set the User property on incoming requests; and
3. Annotate your controllers and methods to enforce authorization constraints.

These steps will now be explained in detail.

1. Set an Authorization Provider #

The first step to setting up authorization in your application is to create an Authorization Provider that runs your user authorization logic. Your Provider must implement the diego.security.AuthorizationProvider interface.

This is the default authorization provider that Diego uses. It checks to ensure that the user has the right permission to access a resource:

public class DefaultAuthorizationProvider implements AuthorizationProvider {
    @Override
    public boolean isAuthorized(User user, String[] requiredAuthorities) {
        return requiredAuthorities.length == 0 || user.hasAuthority(requiredAuthorities[0]);
    }
}

If you wanted to do role-based authorization, you would use the User.isInRole() method instead.

Once your Authorization Provider has been created, adjust your application’s configuration as below:

diego.security.authorizationProver = "com.myapp.MyAuthProvider"

2. Set the User object on incoming requests #

Now that you have an Authorization Provider set up to inspect user permissions, you need to set the User property on incoming requests. This can be done using a Filter:

public class MyApp implements WebMvcConfiguration {
    
    @Override
    public void configure(WebMvcApplication app) {
        app.addFilter(ctx -> {
            User user = new User(1, "claude@lcmail.com", List.of("manage_users", "manage_posts"));
            ctx.setUser(user);
        }).addUrlPattern("/admin/*");
    }
}

In the example above, the user Claude with an ID of 1 and permission to manage users and posts has been set on all requests going to /admin/*.

3. Annotate your controllers and methods to enforce constraints #

Use the @Secure and @Check annotations to lock down your controllers and endpoints.

• The @diego.security.Secure annotation checks to ensure that the User property is available on an incoming request;
• The @diego.security.Check annotation assists the configured Authorization Provider by supplying the requiredAuthorities argument;
• You can use both the @Secure and @Check annotations on classes, but only the @Check annotation on methods;
• You can use only @Check on your methods without including the @Secure annotation on the class.

The last step is for us to set constraints on our Admin controller:

@Secure
public class AdminController extends Controller {
    
    @GET("/users/")
    @Check("manage_users")
    public Result manageUsers() { ... }
    
    @GET("/posts/")
    @Check("manage_posts")
    public Results managePosts() { ... }
}

In this controller, only users with the manage_users permission can access /admin/users/ and only users with the manage_posts permission can access /admin/posts/.

Overriding Authorization #

In some cases, you’d want to override the required permissions for one resource. You can do that by setting the @Check annotation on the controller class with the base permission (which would apply to all controller endpoints), and then applying another @Check annotation to the methods that require special permissions:

@Secure
@Check("admin")
public class AdminController extends Controller {
    
    @Check("read_logs")
    @GET("/logs")
    public Result getRecentLogs() { ... }
}

In the above example, we are ensuring that all endpoints in the controller will require admin privileges, but to access the getRecentLogs() endpoint, the user must have the read_logs permission.

The User object #

The User object represents an authenticated User. This object is meant for use in the security context and should not be extended or melded with domain models; your Customer model should not extend User, for example.

In a typical application, you would store the user’s ID for finding the full record in the database, a display name such as a first name or an email address for displaying in views and a role or list of permissions applicable to the user. This is similar to other popular authorization frameworks such as Firebase auth.

Next Configuration

#