How to Extract the UPN from a Digital Certificate on a CAC card using F5 APM
Introduction This article describes two different methods to extract the UPN from the digital certificate for further processing by the BIG-IP. While there are other excellent articles that show you how to build out the entire access policy, this article concentrates on the methods for extracting the UPN. Some Context The CAC card is a "smart" card about the size of a credit card, it is the standard identification for active duty uniformed Service personnel, Selected Reserve, DoD civilian employees, and eligible contractor personnel. It is also the principal card used to enable physical access to buildings and controlled spaces, and it provides access to DoD computer network and systems. Accessing DoD PKI-protected information is most commonly achieved using the PKI certificates stored on your Common Access Card (CAC). The certificates on your CAC can allow you to perform routine activities such as accessing OWA, signing documents, and viewing other PKI-protected information online. In F5, the typical authentication motion for F5 Access Policy Manager when dealing with common access cards is to:- Present a DoD Warning Banner Validate the Certificate through TLS Validate that the certificate has not been revoked Pull the UPN field of the certificate to search for the user in LDAP The F5 Access Policy Manager uses the Universal Principal Name (UPN) taken from the Subject Alternative Name (SAN) field of the Signature Certificate to search for the user in LDAP and allow or deny access based on the information found. The diagram below shows the value that we will be pulling from the certificate to use for further authentication. On a DoD CAC the UPN would be of the format EDIPI@mil. The following describes two methods to extract the UPN as part of an APM policy. If you prefer, I have published a 5-minute demonstration video outlining the steps presented in this article. Otherwise, you may continue reading, or refer back at your desired pace, to the step-by-step presented below. Method One – a Variable Assign within an access policy This method relies on the use of an access policy item called a “Variable Assign” that contains a custom expression. In the diagram below we are placing a variable assign access policy item after checking that the certificate is valid through mutual tls with the On Demand Cert Auth and then checking with an OCSP server that the certificate has not been revoked via OCSP. To add the variable assign click the ‘+’ item in the visual policy editor and select the variable assign item in the visual policy editor. The variable assign is under the Assignment tab in the Visual Policy Editor. In the variable assign give the access policy item a name for instance “upn_extract” and then click the “Add New Entry” button. Then ensure that Custom Variable is selected Create a variable name – for instance session.custom.upn On the right side select “Custom Expression” And place the following expression in the entry field below.. this expression parses the x509 certificate attributes on the CAC card for the UPN. set x509e_fields [split [mcget {session.ssl.cert.x509extension}] "\n"]; # For each element in the list: foreach field $x509e_fields { # If the element contains UPN: if { $field contains "othername:UPN" } { ## set start of UPN variable set start [expr {[string first "othername:UPN<" $field] +14}] # UPN format is <user@domain> # Return the UPN, by finding the index of opening and closing brackets, then use string range to get everything between. return [string range $field $start [expr { [string first ">" $field $start] - 1 } ] ]; } } # Otherwise return UPN Not Found: return "UPN-NOT-FOUND"; Click “Finished”. Method Two – an Access Policy Agent Event with an iRule The second method relies on the use of an access policy item called an “iRule Event” that uses an iRule to extract the UPN. In the diagram below we are placing an iRule event access policy item after checking that the certificate is valid through mutual tls with the On Demand Cert Auth and then checking with an OCSP server that the certificate has not been revoked via OCSP. To add the iRule Event click the ‘+’ item in the visual policy editor and select the variable assign item in the visual policy editor. The iRule Event is under the General Purpose tab in the Visual Policy Editor. Then provide a name and a Custom iRule Event Agent ID. I like to make the name the same as the identifier, but they can bet different. The custom iRule Event Agent ID ties the visual policy editor iRule event item to an iRule. Create the iRule. Now under Local Traffic/iRules click the create button. Provide a name for the iRule. And place the following iRule in the entry field this iRule parses the x509 certificate attributes on the CAC card for the UPN. when ACCESS_POLICY_AGENT_EVENT { if { [ACCESS::policy agent_id] eq "CERTPROC"} { # This event extracts the user principal name from a client-certificate and places it into a session variable. if { [ACCESS::session data get session.ssl.cert.x509extension] contains "othername:UPN<" } { ACCESS::session data set session.custom.upn [findstr [ACCESS::session data get session.ssl.cert.x509extension] "othername:UPN<" 14 ">"] } } } Click “Finished” Then on the virtual server that provides the service select “Resources” and then select “Manage” Finally move the CERTPROC iRule from available to enabled. Conclusion Both of these methods will ultimately result in the user principal name, the “UPN” being stored in a session variable within the access policy. This session variable can then be used in an LDAP lookup that can verify that the user exists within the directory and can also be used to pull further information from the directory that will enable additional verification and authentication. Examples might be performing single sign on to an application or determining group membership. Which one is better? (Editorial Time) While both methods are completely valid. I prefer the variable assign within an access policy as it provides a single place in the VPE where the configuration resides. It also allows for a more rapid understanding of the configuration from a troubleshooting perspective as the expression resides within the visual policy. The iRule method means there will be multiple locations where the configuration resides, an experienced APM administrator will be able to quickly determine that an iRule is being used, for a less experienced APM administrator this may take some more time to determine that an iRule is being used and this could hinder future trouble shooting. On the other hand the iRule method is more performant than the expression method and may be a better for a high traffic APM VIP.
