FIDO2

ISAM FIDO2 – Usernameless login and Mediators

Share this post:

This article is the second in a technical series on configuring and using FIDO2 capabilities in ISAM 9.0.7. If you haven’t already done so, please read and complete the exercises in my first FIDO2 technical article as here I’ll be picking up where that one left off.

Configuring a credential viewer

Anyone working with ISAM for some time knows that it’s really important when solutioning to be able to introspect an ISAM credential to see what attributes it contains. This is necessary for debugging a variety of authentication, identity propagation and authorization use cases. I’ve written many articles in the past that include discussions on viewing your ISAM credentials, including these:

I also host a junction-able epac viewer on https://genericeai.mybluemix.net/epac.jsp which I wrote about in this article on certificate linking.

Additionally ISAM ships with an internal demonstration application (turned off by default) that can display credential attributes for you, and from ISAM 9.0.5.0 onward this is quite easy to set up with just a couple of advanced tuning parameters. Let’s do that now.

In the LMI, navigate to Secure Access Control -> Advanced Configuration. Filter on “demo”, and set the following advanced configuration properties:

  • live.demo.enabled = true
  • live.demo.settings = lmiHostAndPort=isam.iamlab.ibm.com:443,lmiAdminId=xxx,lmiAdminPwd=xxx,acHostAndPort=isamruntime:443,websealHostNameAndPort=www.iamlab.ibm.com:443,acUuidCookieName=acuuid

Note that for the purposes of using the demo application as a credential viewer it is not necessary to provide valid LMI admin credentials. You can find documentation on these parameters in the Knowledge Center here.

We also need to apply an ACL to allow authenticated users to access the demo application diagnostics page. Assuming you are running ISAM from docker-compose per Jon’s lab, you can do this with a single command:

$ docker exec -t iamlab_isamconfig_1 pdadmin -a sec_master -p Passw0rd acl attach /WebSEAL/isamconfig-rp1/mga/mobile-demo default-webseal

Deploy changes and publish the snapshot. When the WRP and runtime restart with the new snapshot, you should be able to view your credential at:

https://www.iamlab.ibm.com/mga/mobile-demo/diag/

Don’t worry about errors displayed in some sections of the diag page – only concern yourself with the Access Manager Credential section.

 

The credential viewer will prove useful in later scenarios.

Update emily’s account to contain an email address, and load it into the credential at login

In this section we’re going to configure additional attributes on emily’s account in LDAP, and use the ISAM tag/value attribute support to load that into the credential at authentication time. The reason we’re doing this now is to demonstrate some considerations you need to keep in mind when implementing Username-less login later on, and to show how FIDO2 mediators work and how they can help with Username-less authentication scenarios. For now, follow along and it will hopefully all make sense later.

Run the following command to add an email address to emily’s LDAP record (just paste all the bolded content):

$ docker exec -i iamlab_openldap_1 ldapmodify -h openldap -p 389 -D cn=root,secAuthority=Default -w Passw0rd <<-EOF
dn: uid=emily,dc=ibm,dc=com
changetype: modify
add: mail
mail: emily@iamlab.ibm.com
EOF

Validate that it worked with:

$ docker exec -i iamlab_openldap_1 ldapsearch -h openldap -p 389 -D cn=root,secAuthority=Default -w Passw0rd -b "uid=emily,dc=ibm,dc=com" -s base "(objectclass=*)"

Look for a line under emily’s record with the mail attribute:

mail: emily@iamlab.ibm.com

Verify that the WRP config file includes these entries for adding this LDAP attribute to the credential at authentication time (they were already present in my file after doing the lab, since this is done for you when configuring the WRP for AAC):

[TAM_CRED_ATTRS_SVC]
eperson = azn_cred_registry_id

[TAM_CRED_ATTRS_SVC:eperson]
emailAddress = mail
mobileNumber = mobile

Now re-visit the credential viewer (use https://www.iamlab.ibm.com/pkmslogout if necessary, then login again), and observe that emily’s email address is part of the access manager credential This should also work if you perform authentication via the AAC policy from the previous article.

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

 

 

Implement and test Username-less login

Let’s create a new AAC authentication policy, almost identical to the one from the last article, except this time it will ONLY contain the FIDO2 WebAuthn Authenticator mechanism (no Username Password mechanism), and we’ll call it fido2usernameless:

Don’t forget to deploy pending changes and publish the configuration.

We now (as emily) have to register a Resident Key Credential as part of our FIDO2 registration. To do this you’ll need a browser and authenticator that supports resident key credentials. This is a moving target as browser and authenticator support keeps evolving, and Philip Nye has written this article about the topic. Suffice to say, if you have a combination of browser and authenticator that works, follow along. At the time of writing this article, I can use my Mac Touchbar with Chrome v77 (which is the Chrome Canary version) and it will work as a resident key credential, so that’s what I’m going to do.

Follow the steps shown:

 

From a logged-out state (again use https://www.iamlab.ibm.com/pkmslogout if needed), access the username-less policy:
https://www.iamlab.ibm.com/mga/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:fido2usernameless

Complete FIDO2 authentication using your resident key registration, then visit the credential viewer. You should be successfully logged in as emily!

 

ISAM AAC Point-of-contact type

When using AAC for authentication ISAM, the way the credential is built is strongly influenced by the configured point-of-contact type. This changes the type of EAI authentication headers that AAC sends back to WebSEAL, and permits, for example, AAC (or federated single sign-on) to be used for asserted identity login, such as documented in my WebSEAL without a user registry article. FYI – information about the techniques described in that article were later updated in this post by Philip Nye.

Many customers leverage this technique to provide transient authentication to WebSEAL without having to create ISAM LDAP records for every user. For illustrative purposes we are now going to change the point-of-contact type in AAC and see how that influences username-less login.

  • Navigate to Secure Access Control -> Point of Contact, and change the “current” point of contact type to Access Manager Credential (or Non-Access Manager Username, Access Manager groups and extended attributes).
  • Deploy changes and publish the configuration.

Now perform username-less login again with your FIDO2 resident key credential, and then visit the credential viewer. Notice that the attributes DO NOT contain the email address any more! This is because with the previous point of contact type WebSEAL was building the initial credential by going back to LDAP (and using the TAM_CRED_ATTRS_SVC configuration in the WebSEAL config file), then adding in other attributes from the AAC login response. Now AAC is building an entire credential itself WITHOUT this LDAP process, so the email address attribute is not available.

The same problem can also be observed if you started from an unauthenticated state and accessed the AAC fido2 step-up login policy we created in the previous article.

Regardless of how a user authenticates, you really want a system where at the end of that process the credential contains the same set of standard attributes that might be needed for authorization, or business applications may want to consume via down-streamed HTTP headers.

What are our options for getting the attribute back into the credential at authentication time?

Turns out there are several ways:

  • We could add an Infomap-based mechanism after the FIDO2 WebAuthn mechanism that used UserLookupHelper to retrieve the LDAP attribute for emily and add it to the credential.
  • We could use UserLookupHelper directly from the global AuthSvcCredential mapping rule that runs at the end of every AAC policy to determine the attribute was not present and populate it from LDAP.
  • We could (and will in this case) store the attribute value as being “associated with” the FIDO2 registration during registration time, and re-populate it during FIDO2 usernameless authentication. Whilst for LDAP-specific attributes I would normally recommend one of the above two previous approaches (because you are going back to the source of truth for the attribute value), the technique we are going to show here with FIDO2 mediators would also work for credential attributes that were not originally sourced from LDAP (e.g. they might have arrived in the credential during federated SSO into ISAM, or a social login).

Introducing FIDO2 Mediators

Put simply a FIDO2 mediator is a server-side hook point in the FIDO2 registration and authentication ceremonies within the ISAM FIDO2 service. In ISAM they are implemented as Javascript mapping rules and allow for your own code to run during critical phases of FIDO2 processing.

You can read more about FIDO2 Mediation in the ISAM Knowledge Center here.

There is an example mediator with several flagged-out scenarios available for download from ISAM. Find the example at Manage System Settings -> File Downloads then look under access_control/examples/mapping_rules/fido2_mediator.js:

 

 

Download this example now, and take a look at the provided code. For our purposes we are going to add the modify that example as follows:

1. In the mediate_attestation_result function, add the following code to preserve attribute values at registration time:

var attributesWeCareAbout = [ "emailAddress" ];
for (var i = 0; i < attributesWeCareAbout.length; i++) {
    val = stsuu.getAttributeValueByName(attributesWeCareAbout[i]);
    if (val != null) {
        associate_attribute(attributesWeCareAbout[i], val);
    }
}

3. In the mediate_assertion_result function, add the following code to restore the attribute values into the credential at authentication time:

for (var i in context.requestData.registration.attributes) {
    credentialData.put(i, context.requestData.registration.attributes[i]);
}

Now use the LMI to upload this updated mediator and modify our relying-party to use it.

  • Navigate to Secure Access Control -> FIDO2 Configuration -> Mediators.
  • Import the mediator file.
  • Edit the existing FIDO2 relying party configuration, and set this mediator for the RP.
  • Press Next, and Save the updated FIDO2 relying party configuration.
  • Deploy changes and publish the configuration.

 

Now you will need to re-register your authenticator and check this all works.

Follow these steps carefully:

If you have any issues, you can use the IDMappingExtUtils.traceString method in the mediator, turn on com.tivoli.am.fim.sts.utilities.*=all trace in the runtime using the LMI, and use the trace.log of the isamruntime container to debug what is happening. I tend to do this a lot!

Finally, let’s add one more attribute to the credential at authentication time. Edit the mediator in the LMI, and in the mediate_assertion_result function, add this code at the end:

// dump the entire available context in the credential for demo/debug purposes
credentialData.put("fidoLoginDetails", JSON.stringify(context));

Save, deploy and publish the configuration, then re-perform usernameless login. Take a look at the credential now, and the rich data available in the fidoLoginDetails attribute.

There will be even more data available when we start looking at attestation and metadata, but that’s a topic for my next article…

More FIDO2 stories

Cloud Identity FIDO2 – Consuming FIDO2 as-a-service from IBM Cloud Identity

This article introduces a free, open-source sample application which demonstrates how an external FIDO2 relying party can consume IBM Cloud Identity APIs as-a-service. The application has been written in Node.js and leverages a range of API calls from IBM Cloud Identity (CI) including: User Management FIDO2 APIs OAuth and OpenID Connect Integration The application has […]

Continue reading

FIDO2 for IoT – A hobby project

In our work at IBM building FIDO2 services for both on-premise (IBM Security Access Manager) and cloud (IBM Cloud Identity) offerings, we have been looking at scenarios for using FIDO2 authentication technology beyond the mainstream use case of browser-based authentication with WebAuthn. One scenario we decided to experiment with is FIDO2 for IoT devices – […]

Continue reading

The fido2viewer – a free FIDO2 debugging utility

Those of you who have been reading my recent series of blog posts will realize that I’ve been spending a great deal of time working on FIDO2 and WebAuthn related technologies. As part of this effort which has been in progress on and off for more than 12 months now, I put together a debugging […]

Continue reading