Notifications During Authentication Life Cycle

A quick blog discussing some of the simpler ways of handling authentication session life cycle notification in ForgeRock Access Management.

Firstly, a few definitions.  Authentication - working out who someone or something claims to be.  Generally handled via a login flow.  Authentication life cycle?  Well, that login process needs a start and an end - and also, at the end of the login process, there is typically a session life cycle process too. So what are notifications.  Pretty simply, messages sent to 3rd party systems that rely on either the authentication or session service to perform local actions.  Eg an application using a session token to allow access.

So why is this interesting?  An example couple of use cases include notifying a 3rd party when a user on a particular device has logged in - perhaps a honey pot system - or notifying a relying party that a session has ended, in order to terminate any local sessions within an application.


Let's start at the end first.  In ForgeRock Access Management 6.0, a feature called Treehooks was created - with a specific Treehook, called a Logout Webhook implemented.  This Webhook, replaces some of the functionality that used to be performed by the post authentication plugin onLogout() method.

Webhooks sit within the Authentication config area and are pretty trivial to setup.

The configuration is basically details that describe where the notification will go - namely an HTTP endpoint, delivered over a POST request.  So we simply enter the necessary headers and body etc.  The body by design has access to several variables.  These variables are fully described here, but basically contain information that relates to the issued session object.

So how do we use this webhook?  Firstly just create a basic intelligent authentication tree, and add in the Register Logout Webhook authentication node.  It only has one config item - just a drop down of the previously created hooks.  Chose the appropriate one.

Notify Request Node

In addition to the log out webhook, there is also a ForgeRock Marketplace HTTP Notify Request Node.  This is basically the same as a logout webhook, except it can be placed at any part of the authentication tree.  To configure, simply build and add to your deployment and drag onto the intelligent auth tree canvas. The configuration is similar to the logout webhook, in the sense this is a HTTP POST request, requiring the necessary body and headers.  The main difference here of course, as there is no session created yet, the number of variables is limited to the ${username}.  You could easily extend this of course if more information from the auth tree shared state was needed.

So we now have a final tree that looks something like the following:

This is a simple username and password tree (passwords are gonna live forever right??).  During login a sample API, will receive a message saying a user has logged in.  On the termination of the session (via a logout) the API will also receive a message.  The session termination event type is also captured - this is subtly important as the termination may have come about from a user logout, session idle timeout, session timeout or even an administrative termination.