Username Mapping for Client Certificates

I recently had a chance to migrate a basic Client Certificate environment from TAM 6.1.1 to ISAM 9.0.1.0.  If you haven’t looked at Client Certificate mapping – my colleague Phil Nye has a great primer.

However – when I checked out the documentation – the Client Certificate mapping page states it is due to be deprecated in favour of the the Authenticated User Mapping function.  I’m not entirely sure when this went into fruition – but the Authenticated User Mapping solves one of the big challenges I’ve had with Client Cert Mapping in the past.  It can now add additional attributes – not just a single username.

This was perfect was what I needed to do.  The TAM 6.1.1 environment used a Client Cert EAI which would return the user’s identity and a custom tagvalue attribute.  I needed to perform the following:

• Validate the Client Certificate
• Extract the username.  The certificate was issued to “username@local_domain” and had that as the SubjectCN.
• Add an additional attribute: tagvalue_userid.  This had to be set to the username as well.

It’s worth noting that the Authenticated User Mapping really required you to use the documentation.  I didn’t realise this and had jumped right in – configuring it and looking through the trace logs.  However – I couldn’t find the SubjectCN anywhere.  In the list of Valid User Mapping attributes there is a line:

The x509 data, except for the x509 extensions, is included in the constructed XML document only if it is required by the rule.

Once I added something containing x509.subject_cn to my mapping rule – I could see the attribute in the trace.

In the end – the mapping rule was very simple:

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser" version="1.0">
  <xsl:output method="xml" omit-xml-declaration="yes" encoding='UTF=8' indent="no"/>
  <xsl:template match="text()"></xsl:template>
  <xsl:template match="/XMLUMI/stsuuser:STSUniversalUser/stsuuser:AttributeList">
    <identity><xsl:value-of select="substring-before(stsuuser:Attribute[@name='x509.subject_cn']/stsuuser:Value, '@' )"/></identity>
    <attribute name='tagvalue_userid'><xsl:value-of select="substring-before(stsuuser:Attribute[@name='x509.subject_cn']/stsuuser:Value, '@' )"/></attribute>
  </xsl:template> 
</xsl:stylesheet>

There isn’t too much too much to say on that rule.  The <identity> tags outline my username.  The <attribute> tags (you can have as many as needed) outline all of the additional attributes added to the PAC.  There’s a very basic XSL transform: substring-before(<TEXT>, ‘@’ ).  That grabs the username out of the subject_cn.

Once a mapping rule is created (in Secure Web Settings > Global Settings > User Name Mapping) – enable it in a reverse proxy instance by:

[user-map-authn]
# Specify the mapping file you created
rules-file = client_cert_mapping
# Enable/Disable tracing.  
debug-level = 0

Don’t forget that you can use LDAP lookups, hardcoded text and more complex XSL Transforms to build out the required attributes.