Written by Simon Moffat
Summary
Handling authentication session life cycle notification in AM.
In this article, we’ll discuss some of the simpler ways of handling authentication session life cycle notification in ForgeRock Access Management.
Firstly, a few definitions. Authentication is working out who someone or something claims to be. This is generally handled via a login flow. The authentication life cycle? Well, that login process needs a start and an end. Also, at the end of the login process, there is typically a session life cycle process. So, what are notifications? Pretty simply, messages sent to third-party systems that rely on either the authentication or session service to perform local actions. For example, an application using a session token to allow access. So why is this interesting? Some example use cases include notifying a third 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.
Webhooks
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 set up:
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, and so on. 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 the Register Logout Webhook authentication node. It only has one config item; select it from the drop-down menu of the previously created hooks. Choose the appropriate one:
Notify Request Node
In addition to the Logout 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, add to your deployment, and drag it on the intelligent auth tree canvas. The configuration is similar to the Logout Webhook in the sense that this is a HTTP POST request, requiring the necessary body and headers. The main difference here, as there is no session created yet, is 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 that a user has logged in. When the session is terminated (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.