Interceptor: how to set up the interactive user profiles selection feature

Introduction to Interceptor


The most common login flow in Safewhere*Identify is:

  1. 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 log in.
  2. The provider returns a token to Safewhere*Identify. Safewhere*Identify validates the token and creates a local authentication session (*).
  3. The token is then passed (**) to the claims transformation pipeline and returned to the service provider.

Please note that (*) happens on the authentication side, whereas (**) 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 include:

  • Check if a token meets some custom conditions. For example, a login user must belong to some specific organizations.
  • Display a UI to prompt a user for more information.
  • Use the token to look 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 box that lists all profiles so that the user can select one. This is actually a built-in feature of Identify.

In previous versions of Safewhere*Identify, custom plug-ins are usually the way to go. Some simple scenarios that don't need user interaction might make use of custom claims transformation. But that is no longer the case. Starting with 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 his or her own code to customize the workflow. Coding-wise, an interceptor is nothing more than a class that implements a required interface.

More details about the interceptor can be found  here.

Sample Use Case


Imagine we have a federation as follows:
- An organization uses Identify as its Identify Provider for its Service Providers. All users can use Facebook accounts to log in.
- The organization also has an AD to store its 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 nonpowered profile for daily work. All profiles of a user have the same email address.
- When a user, whose name is Alice, accesses an Service Provider, she is redirected to Identify and is then redirected to Facebook to perform login. Most likely, she has opted to always log in 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 uses the email address stored in the token to look for all of Alice’s accounts in the local stores: Active Directory or Identify. All the found accounts are shown to Alice so that she can decide which account she really wants to log in as.

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 Identify Provider, 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 Service Providers, Identify has a built-in interceptor called User profiles interceptor, which can be used to fetch users’ 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 Active Directory Store for a Facebook Connection


1. On Identify*Admin, open to edit a Facebook Authentication Connection. Scroll down to the interceptor section

Interceptor Section
2. Check the "Intercept login flow" check-box.
3. Leave the "Name of the main view" text box blank to use the default view.
4. In the Interceptor type name drop-down list, select "Safewhere.IdentityProvider.RuntimeModel.Interceptors.AuthenticationUserProfileSelectorInterceptorService, Safewhere.IdentityProvider.RuntimeModel"
5. In the Interceptor's dependency type drop-down list, select "Safewhere.External.Samples.LdapUserProfileService, Safewhere.External.Samples".

Interceptor Section Setting
6. Next, add three 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.
  • The third setting is ldapwsServerName, which specifies the LDAP-WS server that should be used as a proxy to the real AD.

The two above 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.".

interceptor - LDAPSW config

 

Configuring User Profiles Interceptor with Local Identify Store for a Facebook Connection


1. On Identify*Admin, open to edit a Facebook Authentication Connection. Scroll down to the interceptor section

Interceptor Section
2. Check the "Intercept login flow" check-box.
3. Leave the "Name of the main view" text box blank to use the default view.
4. In the Interceptor type name drop-down list, select "Safewhere.IdentityProvider.RuntimeModel.Interceptors.AuthenticationUserProfileSelectorInterceptorService, Safewhere.IdentityProvider.RuntimeModel"
5. In the Interceptor's dependency type drop-down list, select "Safewhere.External.Samples.LocalStoreUserProfileService, Safewhere.External.Samples".

2018-02-01_11-22-38
6. Next, add three additional key-value pair settings, which are required by the LdapUserProfileService:

  • The first is identityLocalClaimType= the Identify claim type, which is needed to do a look up against a local user store.
  • The second one is identityClaimType= "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" from social IdP

The two above settings mean "extract the claim value whose type is "http://.../emailaddress" from the token (which is of type ClaimsPrincipal) and compare it to Identify's claim attribute to look up for users."

Note: when using this interceptor, the matching profiles must have the value at the Name claim type.

2018-02-01_11-52-32