Introduction to Interceptor
The most common login flow in Safewhere*Identify is:
- A user accesses a service provider and is redirected to Safewhere*Identify. Safewhere*Identify then redirects the user to an authentication provider where he or she will enter credentials to login.
- The provider returns a token to Safewhere*Identify. Safewhere*Identify validates the token and creates a local authentication session (*)
- The token is then passed (**) to claims transformation pipeline and returned to the service provider.
Please note that (*) happens on the authentication side while (**) happens on the protocol side.
In reality, our customers usually have high needs for the ability to intercept after a token is received but before an authentication session is created in (*), or before the token is passed to the claims transformation pipeline in (**). Some of the use-cases included:
- Check if a token meets some custom conditions. For example, a login user must belong to some specific organizations.
- Display a UI to ask a user for more information.
- Use the token to look up for matched accounts (aka profiles) in the Safewhere*Identify‘s local user store or in an AD. If there are multiple matches, display a dialog which lists all profiles so that the user can select. This is actually a built-in feature of Identify.
In previous versions of Safewhere*Identify, custom plugins are usually the way to go. Some simple scenarios which don’t need user interaction may make use of custom claims transformation. But that is no longer the case. From version 4.1, Identify has a new feature called “interceptor” which can help do all the use cases above easily. Safewhere*Identify provides two extensible points at (*) and (**) where a customer can inject their own code to customize the workflow. Coding-wise, an interceptor is nothing more than a class which implements a required interface.
More details about Interceptor can be found here.
Sample use case
Imagine we have a federation as follows:
– An organization uses Identify as their IdP for their RPs. All users can use Facebook accounts to login.
– The organization also has a AD to store their local users.
– One user may have multiple accounts (also called profiles in the context of this topic) in the local AD.
For example, a system administrator may have an SA profile, and a non-powered profile for daily work. All profiles of a user have the same email address.
– When a user, whose name is Alice, accesses an RP, she is redirected to Identify and is then redirected to Facebook to perform login. More often than not, she has opted to always login and thus doesn’t need to enter credentials.
– What we need to achieve here is interesting and useful: after receiving a token from Facebook, Safewhere*Identify will use the email address stored in the token to look up for all Alice’s accounts in the local AD. All the found accounts will be shown to Alice so that she can decide what account she really wants to login as.
In order to support this use case, we need a new feature of Safewhere*Identify 4.1 called Interceptor that allows intercepting the login flow:
– Right after Safewhere*Identify receives a token from an IdP, but before Identify uses that token to create a login session for the user.
– Before Safewhere*Identify feeds the token to the claims transformation pipeline and issues it to RPs.
Identify has a built-in interceptor called “User profiles interceptor” which can be used to fetch user’s profiles from a store and allow a user to interactively select the one that he or she wants to use.
Configuring User Profiles Interceptor with AD store for a Facebook connection
1. On Identify*Admin, open to edit a Facebook authentication connection. Scroll down to the interceptor section
3. Check the “Intercept login flow” check-box.
4. Leave the “Name of the main view” textbox blank to use the default view.
5. On the Interceptor type name drop down list, select “Safewhere.IdentityProvider.RuntimeModel.Interceptors.AuthenticationUserProfileSelectorInterceptorService, Safewhere.IdentityProvider.RuntimeModel”
6. On the Interceptor’s dependency type name, select “Safewhere.External.Samples.LdapUserProfileService, Safewhere.External.Samples”.
7. Next, we need to add 3 additional key-value pair settings which are required by the LdapUserProfileService.
- The first is identityClaimType = claim type which is set as Email claim type at System setup page
- The second one is identityAttributeName = mail. These two settings mean “extract the claim value whose type is “http://…/emailaddress” from the token (which is of type ClaimsPrincipal) and compare it to AD’s mail attribute to look up for users”.
- The third setting is ldapwsServerName which specifies the LDAP-WS server which should be used as a proxy to the real AD.
