Authentication Service Plugin API

Intro

Authentication Service Plugin API can be used to create plugins which can extend the authentication/authorization functionality of Gentics Mesh.

Those plugins are intended to work in conjunction with the OAuth2 interation. When the OAuth2 integration with the Keycloak Identity Provider is enabled Gentics Mesh will automatically sync users provided by Keycloak with the users that are stored in Gentics Mesh.

Once a JWT has been obtained by keycloak it can be used for Gentics Mesh requests. The token is validated and the user is synced.

Often it is however also desired to sync permission specific information from identity provider. This is where most of the Authentication Service Plugin API comes into play. The API can be used to create plugins which map the information from the JWT to Gentics Mesh roles and groups.

This way any public claim information from the JWT can be used to dynamically update the user, create roles and groups.

Flow

A typical request which needs authentication passes through various handlers which try to autenticate. The MeshAuthChain is currently responsible for passing the requests along these handlers.

JWT handler

This handler tries to authenticate the request by validating the JWT against the Gentics Mesh keystore certificate. The identified user will be added to the request when this succeeds. In this case no other authentication handler in the chain is called.

Failed authentications at this stage will yield a Could not authenticate token. warning. This warning will be removed in future versions of Gentics Mesh. The next handler in the chain will be used if the JWT handler was unable to authenticate the user.

OAuth handler

This handler will utilize the configured or provided public keys to validate the request. The AuthServicePlugin API will be called when the request JWT could be validated with the provided public keys.

First the acceptToken method gets called to check if any of the plugins rejects the request.

Next the mapping process will be invoked. The token information will be inspected to check whether a mapping call is needed.

The extractUsername method gets called to identify and load the user. Once the user has been loaded

The jti or iat of the JWT will be used to decide whether a fresh mapping call must be invoked. The JWT will only be passed to the mapping code if it has not yet been handled.

Finally the mapToken method will be called for every AuthServicePlugin.

Anonymous Auth Handler

This handler will only be utilized when no authentication information have been added to the request and when the anonymous authentication has been enabled. The handler will automatically assign the anonymous user to the request and accept it.

Mapping JWT

Table 1. AuthServicePlugin methods excerpt
Method	Description
`AuthServicePlugin#mapToken()`	Use the token information to create a mapping result which will be used to sync user, groups, roles.

The information from the returned MappingResult will be used to sync the elements in Gentics Mesh. Any of the fields in the result can be omitted.

Sync process is as follows:

Update user with MappingResult#getUser information or use default mapper if no user was specified.
Create roles that are listed in MappingResult#getRoles.
Create groups that are listed in MappingResult#getGroups.
Assign user to groups of MappingResult#getGroups list.
Link roles that are listed within MappingResult#getGroups entries to the groups (via GroupResponse#getRoles).
Iterate over all roles of the mapped groups and invoke MappingResult#getRoleFilter to check whether the role should be unlinked from the group. You can use this to ensure that only specific roles are links to the groups.
Link roles that are listed within MappingResult#getRoles entries to the groups (via GroupResponse#getGroups).
Iterate over all groups of the user and invoke MappingResult#getGroupFilter to check whether the user should be removed from the group. You can use this to ensure that the use is only part of specific groups.

A default mapper which maps firstname, lastname, email address will be used for user information if you do not set the user field in the MappingResult object.

The synchronization process will only be invoked if the access token changes. Remember that you need to issue a new access token if you change the mapping in keycloak. The old token may still contain the old information.

It is important to note that the mapper API can not be used to delete users, roles or groups.

Utils

The AuthServicePluginUtils provides additional utility functions that can be used in your plugin implementation. The AuthServicePluginUtils#createRoleFilter() and AuthServicePluginUtils#createGroupFilter() methods can be used to create filters which will only keep role/group, user/group assignments that have been specified in the given lists.

This is useful if you want to ensure that users only belong in the groups that are managed by your identity provider/auth plugin.

Authentication Service Plugin API