Security

This guide describes how to secure your Apache Causeway application by configuring an appropriate implementation of its authentication and authorization SPIs.

Security Architecture

Apache Causeway defines an SPI for both authentication and authorization:

  • By "authentication" we mean logging into the application using some credentials, typically a username and password. Authentication also means looking up the set of roles to which a user belongs.

    The framework allows for different authentication mechanisms through the Authenticator SPI. .

  • By "authorization" we mean permissions: granting roles to have access to features (domain object members) of the app, and granting users to those roles.

    The framework allows for different authorization mechanisms through the Authorizor SPI.

There are several implementations of these SPIs to choose from; these make up the bulk of this guide.

In addition to the security SPI implementations, there are a number of security-related extensions:

  • The Spring OAuth2 extension configures the Spring authenticator for OAuth2 stores (eg gmail, facebook)

  • The SecMan extension provides both an authenticator and an authorizor from domain entities (users, roles and permission entities) using either JPA or JDO.

    As these users, roles and permissions are domain objects, they can be administered through Apache Causeway itself.

Note that authenticators and authorizor components can be mixed. For example, the Keycloak or Spring OAuth2 authenticator can be used with Secman for authorization.

The most significant of these is probably SecMan, which uses a

Permissions

The Authorizor SPI defines two types of permissions:

  • Read permission means that the user can view the object member; it will be rendered in the UI.

    An action with only read permission will be shown disabled ("greyed out"); a property with read-only permission cannot be edited.

  • Write permission means that the object member can be changed.

    For actions this means that they can be invoked.

If there is neither read nor write permissions then the feature will be invisible to the user.

Auditing

A further aspect of security is auditing: recording what data was modified by which user.

Apache Causeway provides the InteractionContext can be used to track the actions being invoked, and the EntityPropertyChangeSubscriber captures what data was modified as a result (auditing). When Interactions are persisted (eg by way of the Execution Log extension) then this provides excellent traceability. The Audit Trail module provides an implementation of the EntityPropertyChangeSubscriber that persists audit entries to the database.

For CommandSubscriber SPI can be also be used to capture actions. The Command Log extension provides a simple implementation of this SPI.

Programmers' API

Generally speaking your domain objects (or more generally your application) should be agnostic of the user/roles that are interacting with them; applying security permissions is the responsibility of the framework.

If you need to determine the identity of the current user, you can usually use Apache Causeway' UserService API, in the form of UserMemento.

For example:

final UserMemento user = userService.getUser();
final List<RoleMemento> roles = user.getRoles();
for (RoleMemento role : roles) {
    String roleName = role.getName();
    ...
}

Each role’s name property encodes both the realm that provided the role, and the role identity itself.

If using the Wicket viewer, then note there will also be another role which is used internally (namely org.apache.causeway.viewer.wicket.roles.USER).