What's new in Errai 3? Part 2: Role-Based Access Control and PicketLink Integration

This is the second post in a series describing new features in Errai 3.0. This article is about Errai Security, which provides role-based access control with optional PicketLink integration.

Errai Security provides a declarative way of securing pages, UI elements, and remote services. Below we'll show how it is used, and how you can use it with PicketLink or another server-side security framework of your choice.

@RestrictedAccess

Role-based access control in Errai Security is focused around the @RestrictedAccess annotation. Whether you're securing a @Page, @Remote interface or UI element, you simply annotate the secured resource with @RestrictedAccess.

The annotation takes an optional array of role names (Strings). For a user to be able to access a resource, they must have all of these roles; if they do not have all of the required roles, we say that the user is unauthorized. @RestrictedAccess without roles blocks access to those not logged-in; if a user is denied access because they are not logged-in, we say that they are unauthenticated.

Restricting @Page

Here is an Errai Navigation @Page that restricts access to users lacking the admin role:

When a user is denied access to this page, one of two things will happen:

• They will be redirected to the application's login page if unauthenticated.
• They will be redirected to the application's security error page if unauthorized.

You can define any Errai Navigation page as login page or security error page with the @Page annotation role attribute. For example, here is a class that functions as both a login and security error page:

Restricting @DataFields

In @Templated widgets, Errai Security can be used to apply CSS styles to template-bound fields (for example for hiding UI elements from unauthorized users).

When a user lacks permissions for one of the @DataFields above, the element in the template will have the CSS class, errai-restricted-access-style, applied. The CSS definitions ensure that the admin anchor will not be displayed to unauthorized users while the logout anchor will only be seen by unauthenticated users.

Restricting Remote Services

Errai Security can be used to secure Errai Bus RPCs, JAX-RS Endpoints, and Errai Messaging Services. When access to a service is denied, a UnauthenticatedException or UnauthorizedException is thrown on the server, which can be handled on the client with an ErrorCallback.

The default error handling provides behaviour similar to @RestrictedAccess on @Pages: unauthorized access causes navigation to the security error page and unauthenticated access causes navigation to the login page.

Errai Bus RPC

Errai JAX-RS Endpoint

Authentication and Server-Side Integration

The single point of contact between Errai Security and your preferred server-side security framework is the AuthenticationService. This interface is used to log in and out, and obtain an instance of the current User. The AuthenticationService is an @Remote interface, so you can use Errai RPC to call it from the client. errai-security-picketlink.jar provides a default AuthenticationService implementation using PicketLink. Using this implementation requires no configuration: just have the jar on your classpath and you're good to go.

Here is a login page that uses an AuthenticationService caller for logging in.

Using a Custom AuthenticationService

Integrating Errai Security with a different security back-end is as simple as implementing the AuthenticationService, and making your implementation a valid CDI bean. You can even implement your own User and Role types: for example, the Errai JPA Demo AuthenticationService uses a custom User implementation that is a JPA entity.

See It In Action

If you'd like to see Errai Security in action, you should checkout the Errai Security Demo. If you have any feedback, we'd love to hear it!