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.
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.
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
This handler will utilize the configured or provided public keys to validate the request.
AuthServicePlugin API will be called when the request JWT could be validated with the provided public keys.
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.
extractUsername method gets called to identify and load the user.
Once the user has been loaded
mapToken method will be called for every
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.
AuthServicePlugin interface must be used for an authentication plugin. This interface provides various methods which will be invoked by Gentics Mesh during the authentication process.
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
Create groups that are listed in
Assign user to groups of
Link roles that are listed within
MappingResult#getGroups entries to the groups (via
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
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
|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.|
AuthServicePluginUtils provides additional utility functions that can be used in your plugin implementation. The
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.