Onegini Hooks is a feature that allows customizing certain user flows. This customization includes:
- rendering additional view
- executing actions that can e.g. modify user's data
There are several flows in which hook can be launched. Currently we support:
- Post Login Hook
Post Login Hook
The Post Login Hook is a hook that is launched after user successfully signs in but before user is redirected to target page which can be, e.g. origin url or service provider page. It supports following Action Types:
Each Hook can consist of supported actions executed in any order. Actions of same type can also be repeated (e.g. it is possible to update user's profile in multiple actions to achieve desired state). In order to start a Hook, first Action Type needs to be chosen. This can be done by implementing appropriate Processing Service (as a Spring bean) in the Extension:
Table below specifies which interface implementation needs to be provided for Hook to be enabled:
|HookType||Processing Service interface|
Each Processing Service can be constructed using builtin builder where you can specify how to initialize the hook (usually with a function interface). Additionally, you can specify Action Type specific handlers which can control the Hook flow and contain logic defining how to process specific action.
Each Hook Action handler returns a
HookResponse object which consists of following data:
- information which Action Type should be executed next
- data returned as a result of processing current action. Structure of this object depends on Action Type.
- session data for current's Hook execution
After an action is chosen, it's being process by the Onegini IdP.
In order to process action of a given type, Extension needs to provide a handler that should be specified when constructing Processing Service.
This handler has access to a
HookActionResultData. The structure of this object depends on Action Type:
Some Action Types -
HOOK_CANCEL - do not provide corresponding implementation of
HookActionResultData. It is only information for Onegini IdP to finish the Hook.
Currently, Hooks support following action types:
Please note that some Hooks might not support all the above types.
HOOK_CANCEL action types are supported by all Hooks.
RENDER_VIEW Action Type should be used when a custom view should be displayed for user. When
RENDER_VIEW is being processed by Extension, it should return following information:
- view name which should be a path to
HTMLtemplate (usually placed in
resouceson Extension side). The
.htmlsuffix does not need to be provided.
- data needed for correctly displaying and handling the view. This data is specified in
propsfield. This map is always placed in ModelMap and is accessible by using key viewData.
When Onegini IdP processes the view (by displaying it to the user), and user submits any form - it is being validated. Errors object is send back to Extension, so it is possible to display the same view for user to have a chance to correct the errors or choose another action in case error exists.
UPDATE_PROFILE Action Type is used to send information to Onegini IdP about attributes that should be updated or removed from user's profile.
UPDATE_PROFILE Action Type, Extension should send back two profiles - one which specifies which attributes should be updated, second one indicates attributes which should be removed.
After Onegini IdP processed the action, it will respond with user's full profile with requested changes. Please note that:
UPDATE_PROFILEaction can be executed multiple times in a sing Hook and all changes are being applied on the profile
- changes made by
UPDATE_PROFILEaction are not persisted until the whole Hook completes successfully
- updating and deleting attributes with
UPDATE_PROFILEAction Type follows the same logic as processing responses in
BLOCK_ACCOUNT action it is possible to move user's current status to BLOCKED. This action should be executed at most once during a Hook. The only data that Extension should provide
is the reason explaining why user is being blocked. Similarly to UPDATE_PROFILE action, status is effectively changed when Hook completes.
Blocking user does not cancel result of other actions (e.g. in case there was an UPDATE_PROFILE executed during the flow, changes in the profile are still persisted).
This action shows view to the user where user's password can be changed. The view allows user to make two actions on it:
- submit the changed password
- cancel the hook
Submitting the view proceeds with following hook actions and at the end of a hook the password is updated (similarly to
When user click's on cancel button, extension decides what to do next (continue, cancel or skip the hook).
HOOK_SKIP action allows user to immediately finish current Hook execution. Using this action does not fail the Hook execution but simply HOOK_SKIPs all other Hook steps
that could have been executed if
HOOK_SKIP action had not been executed.
HOOK_CANCEL action works similarly as
HOOK_SKIP does, i.e. Hook is immediately finished, all other actions are not considered. The main difference is that original process that
lead to triggering the Hook is reverted.
HOOK_COMPLETE is a special Action Type that indicates end of the Hook.
After this action is executed, Onegini IdP commits profile changes applied in other actions and then redirects user to page where user would be redirected in case Hook was not defined or enabled.
When a Hook is defined on Extension, then it is automatically enabled in Onegini IdP. You can change this behavior by specifying enabling property corresponding to given Hook. Please see here for details.
Sometimes some common data might be needed for processing multiple actions, but it might not be available in the returned data provided by Onegini IdP as a result of processing certain action.
In such case it is possible to store this data in session that is managed by Onegini IdP. Each implementation of HookActionProcessingService
provides access to
HookSessionData which is a map in which any objects can be stored. The scope of this session is a single execution of a certain Hook for a given person.