Hooks

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

Hook types

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:

  • RENDER_VIEW
  • UPDATE_PROFILE
  • BLOCK_ACCOUNT
  • CHANGE_PASSWORD
  • HOOK_SKIP
  • HOOK_CANCEL

Developing Hooks

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
Post Login PostLoginHookProcessingService

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.

Action handler

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:

Action Type HookActionResultData implementation
RENDER_VIEW RenderViewHookActionResultData
UPDATE_PROFILE UpdateProfileHookActionResultData
BLOCK_ACCOUNT BlockAccountHookActionResultData
CHANGE_PASSWORD ChangePasswordHookActionResultData

Some Action Types - HOOK_COMPLETE, HOOK_SKIP and HOOK_CANCEL - do not provide corresponding implementation of HookActionResultData. It is only information for Onegini IdP to finish the Hook.

Action Types

Currently, Hooks support following action types:

  • RENDER_VIEW
  • UPDATE_PROFILE
  • BLOCK_ACCOUNT
  • CHANGE_PASSWORD
  • HOOK_SKIP
  • HOOK_CANCEL
  • HOOK_COMPLETE

Please note that some Hooks might not support all the above types. HOOK_COMPLETE, HOOK_SKIP and HOOK_CANCEL action types are supported by all Hooks.

RENDER_VIEW

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 HTML template (usually placed in resouces on Extension side). The .html suffix does not need to be provided.
  • data needed for correctly displaying and handling the view. This data is specified in props field. 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

UPDATE_PROFILE Action Type is used to send information to Onegini IdP about attributes that should be updated or removed from user's profile. When processing 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_PROFILE action can be executed multiple times in a sing Hook and all changes are being applied on the profile
  • changes made by UPDATE_PROFILE action are not persisted until the whole Hook completes successfully
  • updating and deleting attributes with UPDATE_PROFILE Action Type follows the same logic as processing responses in UpdateProfileAttributesExtension and PersonCreationPreProcessExtension

BLOCK_ACCOUNT

With 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).

CHANGE_PASSWORD

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 UPDATE_PROFILE and BLOCK_ACCOUNT). When user click's on cancel button, extension decides what to do next (continue, cancel or skip the hook).

HOOK_SKIP

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

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

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.

Enabling Hooks

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.

Managing session

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.