IBM Security Global Forum

IBM Security Verify Access version 10.0.1.0 is now out the door. Among several new features is the Remember Session capability in the Web Reverse Proxy (WRP). This feature delivers to the browser either via persistent cookie or a HTTP response header an encrypted token which represents the username and (a configurable list of) attributes of the user’s session. Conceptually similar to the idea of a persistent failover cookie (WRP does not support persistent failover cookies), this encrypted token can be presented by the browser back to the Web Reverse Proxy (WRP) to rebuild a user session from an unauthenticated state. You can consider the use of the remember-session function as maintaining a long-lived session in the WRP.

Long gone are the days of shared workstations being commonplace – nowdays the normal scenario is that a user has complete ownership of a device, and typically complete ownership of several devices. As a result, the trend of consumer websites is to allow a user to be “logged in” indefinitely, with perhaps at a minimum a Remember Username capability, and more commonly remaining fully authenticated, only requiring some form of re-authentication when a sensitive operation such as a financial transaction or account security settings update is taking place, or if the user explicitly chooses to sign out.

This article will walk you through a scenario where the remember-session functionality is employed – not using a cookie, but instead using the more advanced technique of HTTP header transmission. The motivation for using the HTTP header approach is both performance (the encrypted token is large, and we don’t necessarily want it sent to the server on every request), and functional. Using the HTTP header approach we are able to control the user experience transitioning from unauthenticated -> authenticated in a carefully orchestrated workflow.

Scenario Overview

This example scenario will be built on top of the completed demonstration scenario I outlined in the FIDO2 in less than 15 minutes with ISAM 9.0.7 use case, although of course it will be using IBM Security Verify Access 10.0.1.0 as the underlying product rather than ISAM 9.0.7. Even if you don’t want to do the exercise yourself, understanding the configuration and why things are done this way will be something you can read about and add to your knowledge bank.

In this example, a user who has never previously authenticated to the WRP will be prompted to authenticate with their username and password. After they have done this, the browser will receive (via HTTP response header) and store their remember-session encrypted token in localStorage in the browser. What will be special about this token though is that the AUTHENTICATION_LEVEL attribute in the token will not be the same as in the user’s real WRP session – instead we will override it with a value of 0. The purpose for this will become clear later – it allows us on future access to use the token to make authenticated API calls to selected endpoints as the user, but not be able create a browser session which can access all protected resources of the server. We can employ protected object policies (POPs) in the WRP to decide which endpoints can be accessed using the token.

When the user logs out of the WRP they will be left with the encrypted token in localStorage. On next visit to the website the login page is loaded, and it will contain Javascript code which can detect the presence of the token in localStorage, and make asynchronous fetch calls back to the server using it. What the fetch call will do is query a FIDO endpoint as the user to obtain assertion options which can include a list of the current FIDO registrations for that user. This is not an API call that can be made unauthenticated, so the token has value here. It is being used as a relatively-low-assurance way of authenticating as the user, just for the purposes of doing further account discovery so that the user can complete re-authentication using a convenient, strong authentication technique (FIDO in this case) instead of a password. If they do not have at least one FIDO registration the login process will fallback to prompting for a password, but if they do have at least one registered FIDO credential then FIDO can be offered as an alternative way of re-authenticating for the user.

I hope that all makes sense, but in case not, here’s a flowchart that I put together that describes how the logic in the login page of the WRP is going to work:

As stated earlier, this article makes the assumption that you have already configured a system with FIDO2 support, as described in the FIDO2 in less than 15 minutes with ISAM 9.0.7 article, however built on top of the IBM Security Verify Access 10.0.1.0 image. That article results in the configuration of an advanced access control (AAC) authentication policy which consists of the UsernamePassword login mechanism followed by the FIDO2 WebAuthn Authenticator mechanism. Confirm that you have this working with your FIDO authenticator by visiting the kickoff URL:

https://www.iamlab.ibm.com/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:fido2

We will now augment this starting configuration with the scenario mentioned above.

Creating an encryption key for remember-session

In the LMI, navigate to System->SSL Certificates, edit the pdsrv keystore. Navigate to the Personal Certificates tab, and create a new self-signed certificate as shown, with key label rememberme:

Enabling Remember Session in the WRP

We are now going to configure the remember-session functionality in the WRP, using the encryption key created above. This will enable the feature using a HTTP header called whoami to transmit the encrypted token, as well as instruct the WRP to override the AUTHENTICATION_LEVEL attribute value with 0.

Edit the WRP configuration file, and make the following stanza updates:

[remember-me]
remember-session-field = hdr:whoami
remember-session-lifetime = -1 
remember-session-key-label = rememberme 
remember-session-attribute-literal = AUTHENTICATION_LEVEL:0

Configuring custom InfoMap authentication

This article is going to use a custom Infomap for authentication as this provides ultimate flexibility over the user experience and data processing.

The technical assets needed to configure the authentication policy, page templates, and mapping rules used in this article are all available in a github repository here:

https://github.com/sbweeden/blog_assets/tree/master/remember_session

Below are the steps required to configure the authentication mechanism, authentication policy, and correct FIDO and AAC authentication logic.

Load the following AAC page templates

Load/update the following AAC mapping rules

Create an InfoMap authentication mechanism using the optionalFIDO.js mapping rule

You will need to deploy changes at this point so that the new authentication mechanism becomes visible to the authentication policy editor.

Create an authentication policy using the InfoMap mechanism

Update the FIDO Relying Party configuration to use the mediator

In the LMI under AAC->FIDO2 Configuration, edit your FIDO2 relying party configuration and add the mediator that was uploaded as a mapping rule:

Update ACL/POP policy

First determine the URL path for your FIDO relying party configuration. This can be seen in the LMI under AAC->FIDO2 Configuration, then look at the endpoints.

Then login to the configuration container using docker, and re-using the built-in pop called favicon which is used to permit browser requests for /favicon.ico at authentication level 0, attach that to the WRP endpoint for assertion options.

We will also attach an unauthenticated-allowed ACL to the fidoLoginHelper.js page, as this is used by our optionalFIDO.html InfoMap page template prior to the user being authenticated.

$ docker exec -it iamlab_isamconfig_1 bash


[isam@isamconfig /]$ pdadmin -a sec_master -p Passw0rd

pdadmin sec_master> pop attach /WebSEAL/isamconfig-rp1/mga/sps/fido2/91da0147-1630-4c65-8585-970421914e64/assertion/options favicon
pdadmin sec_master> acl attach /WebSEAL/isamconfig-rp1/mga/sps/mga/user/mgmt/html/device/fidoLoginHelper.js isam_authsvc_rest_unauth

Update the WRP login_success.html page

When an InfoMap authentication policy authenticates a user, the AuthSvcCredential mapping rule will send a new special EAI response header back to the WRP. This can be seen by inspecting the end of the AuthSvcCredential.js mapping rule file that we previously uploaded:

	if (policyID.equals("urn:ibm:security:authentication:asf:optionalFIDO")) {
	    responseHeaders.put("am-eai-flags", "remember-session,success-page-response");
	}

Notice there are two flags set. The remember-session flag instructs the WRP to invoke the remember session functionality. Because we have configured the remember session functionality to send the token via HTTP header, there needs to be a way for the browser to obtain and store it in localStorage. This is done by way of sending a HTML page back to the browser which can contain javascript to obtain the header value and call the localStorage APIs. That is the purpose of the second flag shown above: success-page-response. This flag will instruct the WRP to send back the login_success.html management page.

In our case we need a customized version of this page to orchestrate the storage of the whoami header value.

Replace the login_success.html page for the reverse proxy with the contents of the one contained in the github repository, as shown below.

https://github.com/sbweeden/blog_assets/blob/master/remember_session/webseal_pages/management/login_success.html

You can inspect the contents of this file to understand how it obtains the header value and stores it in localStorage.

In the LMI, navigate to Web -> ReverseProxy, select the rp1 reverse proxy, client on Manage ->Management Root, and edit the login_success.html:

In the LMI, deploy any pending changes, and publish the snapshot. Wait for the runtime containers to reload and then we’re ready to test it out.

Testing the solution

Access the InfoMap AAC authentication policy with your browser:

https://www.iamlab.ibm.com/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:optionalFIDO

What you should see next is a prompt for username/password authentication, as you will not have an existing whoami remember-session token stored in localStorage that your browser can use to check for FIDO registrations. Login with emily / Passw0rd and noticed that after authentication completes, the ambientCredentials becomes populated in localStorage, including the whoami token value from the remember session functionality.

To recap what just happened, after the AAC policy completed the code in the AuthSvcCredential mapping rule executed, and sent back special am-eai-flags header values to instruct the WRP to execute the remember-session functionality and return the login_success.html page instead of a 302 redirect.

After login_success.html loaded, Javascript on that page read the HTTP header (which was included as a MACRO in the page template), and stored it in localStorage.

If you don’t already have a FIDO2 credential registration, now would be a good time to register one – do that at the user-self-care device management page (this is something that was covered in the pre-req article):

https://www.iamlab.ibm.com/mga/sps/mga/user/mgmt/html/device/device_selection.html

Now logout of the WRP via:

https://www.iamlab.ibm.com/pkmslogout

Then re-visit the AAC authentication policy:

https://www.iamlab.ibm.com/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:optionalFIDO

This time you should be offered FIDO login.

If you look at the Network tab in the browser debugger tools you can see a call is made to the options endpoint. This call is made using fetch, and includes the whoami token as a request header (the header name is the same for both receiving and sending the token, as defined in the WRP configuration file).

You cannot directly access the options endpoint without either having an authenticated session, or using the token, otherwise you will be prompted to login.

At this point you should be able to successfully complete FIDO2 authentication, or fallback to password-based authentication if you wish.

Using remember-me with WRP forms-based login

It is also possible to use the remember session capability when performing regular forms-based username/password login to the WRP, which posts a form to /pkmslogin.form. The way this is done is to augment the login FORM in the WRP login.html file. A version of the updated file is provided for reference in the github repository, however the key thing to note is the inclusion of two special hidden form fields:

<input type="hidden" name="remember-session" value="true" />			
<input type="hidden" name="login-response-type" value="success_page" />

These form field parameters serve the same purpose as the special am-eai-flags values when performing EAI login to the WRP as is done when using an AAC authentication policy. The same login_success.html page is returned when using either EAI or forms-based login.

Debugging – inspecting a remember-session token

In order to determine if your remember-session token is valid and working, possibly the easiest way is to enable the credential viewer local application as I described in my previous article: RIP epac.jsp (2007-2020). Having done that in my WRP, and also attached the favicon POP and an unauthenticated ACL to the /ivcreds resource (same as we did for the FIDO assertion options endpoint earlier in this article), I can now extract my whoami token from localStorage in the browser using the browser developer tools, and play it back to the server with cURL:

export WHOAMI_TOKEN="eyJl....TRUNCATED"

curl -k -H "whoami: $WHOAMI_TOKEN" -H "Accept: application/json" https://www.iamlab.ibm.com/ivcreds | jq .

{
  "AUTHENTICATION_LEVEL": "0",
  "AZN_CRED_AUTHNMECH_INFO": "RememberMe Authentication",
  "AZN_CRED_AUTHZN_ID": "emily",
  "AZN_CRED_AUTH_EPOCH_TIME": "1607665918",
  "AZN_CRED_AUTH_METHOD": "remember-me",
  "AZN_CRED_BROWSER_INFO": "curl/7.64.1",
  "AZN_CRED_IP_FAMILY": "AF_INET",
  "AZN_CRED_MECH_ID": "IV_LDAP_V3.0",
  "AZN_CRED_NETWORK_ADDRESS_BIN": "0xac170001",
  "AZN_CRED_NETWORK_ADDRESS_STR": "172.23.0.1",
  "AZN_CRED_PRINCIPAL_DOMAIN": "Default",
  "AZN_CRED_PRINCIPAL_NAME": "emily",
  "AZN_CRED_PRINCIPAL_UUID": "22621182-38fe-11eb-b107-0242ac120004",
  "AZN_CRED_QOP_INFO": "SSK: TLSV12: 27",
  "AZN_CRED_REGISTRY_ID": "uid=emily,dc=ibm,dc=com",
  "AZN_CRED_VERSION": "0x00001001",
  "SMS_SESSION_REALM": "ISAM-Distributed-Session-Cache",
  "tagvalue_login_user_name": "emily",
  "tagvalue_max_concurrent_web_sessions": "unset",
  "tagvalue_session_index": "fbada1e0-3b74-11eb-b160-0242ac170006",
  "tagvalue_user_session_id": "aXNhbWNvbmZpZy1ycDEA_X9MI/gAAAAIAAAA0/gjTX6iEAfRKfwAASzN6aGp5cjVob1VnY3pZcHhqUXRieWIvVzlXTitWb0kyN0NqKzQ5TjFRbHZqTzZnNVNFPQ==:default"
}

If your whoami remember-session token is not valid (and provided you have allowed unauthenticated access to the credential viewer) you would see an unauthenticated response such as:

{
  "AZN_CRED_AUTH_EPOCH_TIME": "1607665819",
  "AZN_CRED_BROWSER_INFO": "curl/7.64.1",
  "AZN_CRED_IP_FAMILY": "AF_INET",
  "AZN_CRED_MECH_ID": "IV_UNAUTH_V3.0",
  "AZN_CRED_NETWORK_ADDRESS_BIN": "0x00000000",
  "AZN_CRED_NETWORK_ADDRESS_STR": "172.23.0.1",
  "AZN_CRED_PRINCIPAL_DOMAIN": "Default",
  "AZN_CRED_PRINCIPAL_NAME": "unauthenticated",
  "AZN_CRED_QOP_INFO": "SSK: TLSV12: 27",
  "AZN_CRED_USER_INFO": "unauthenticated",
  "AZN_CRED_VERSION": "0x00001001"
}

Summary

The use of remember-session encrypted tokens as a low-assurance authentication credential has the potential to enable new forms of high value, friendly re-authentication experiences for users. Whilst this particular article focused on FIDO credentials for re-authentication, you could also apply this pattern to users who have registered the IBM Verify Mobile application. In that case you would use the remember-session token to discover if the user had a IBM Verify mobile app registration, and if they did offer to perform a push authentication workflow as an alternative with TouchID/FaceID for user verification.

I think that it is important to ensure that your re-authentication flows still employ the “something you know plus something you have or are” philosophy of strong authentication, and you should definitely think like this if the re-authenticated session is being used for sensitive transactions including modification of a user’s strong authentication capabilities. For example I would not perform re-authentication with just a FIDO U2F credential that did not implement user verification – this is why the FIDO2 mediator changes were made to enforce user verification in this article.

In any case, the remember session (and remember-username) capabilities are now a standard part of IBM Security Verify Access and we hope that you will find them useful in your own authentication workflows.

#SecurityExpert