Username Mapping for Client Certificates



I recently had a chance to migrate a basic Client Certificate environment from TAM 6.1.1 to ISAM  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=""; 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>

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:

# 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.



One response to “Username Mapping for Client Certificates”

  1. First.

Leave a Reply

Your email address will not be published. Required fields are marked *