DataPower

DataPower

Join this online group to communicate across IBM product users and experts by sharing advice and best practices with peers and staying up to date regarding product enhancements.

 View Only
Expand all | Collapse all

How to extract Thumbprint and Subject to Validate Incoming Client Certificate

  • 1.  How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Wed May 28, 2025 06:05 AM
    Edited by Krishna Wed May 28, 2025 06:21 AM

    Hello All,

    For each incoming SOAP request, the client certificate's thumbprint and subject must match those mapped to the BID value from the request payload.

    I'm considering to create a MPGW with XSLT and maintaining a mapping file (JSON/XML) in DataPower where each BID maps to its expected thumbprint and subject. On each request, I would:

    • Extract the BID from the payload

    • Get the client certificate's thumbprint and subject

    • Compare them against the mapped values

    If they match, the request proceeds; if not, it's rejected.

    This is my initial plan, but I'm not sure if this is the best way to implement it in DataPower.

    Could you please suggest if this is a recommended approach or share a better alternative or sample?



    ------------------------------
    Krishna
    ------------------------------



  • 2.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Wed May 28, 2025 10:08 AM

    Things to consider:

    1. How are the client certs validated (or is this the validation process)?
    2. Do you issue the client certs?
    3. How many are there?
    4. Do you care about expiration date (which could be answered by q#1 above)?
    5. How do you handle new/reissued certs?
    6. How do you manage obsolete/deleted/no-long-should-be-valid-because-client-is-no-longer-authorized certs?


    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------



  • 3.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Thu May 29, 2025 07:09 AM

    Hello Joseph,

    1. How are the client certs validated (or is this the validation process)? 
      I assume it will be mutual SSL
    2. Do you issue the client certs?
      I think no
    3. How many are there?
      I am not sure but it will be more than 10 
    4. How do you handle new/reissued certs?
      We will configure the new client certs in validation credentials. 
    5. How do you manage obsolete/deleted/no-long-should-be-valid-because-client-is-no-longer-authorized certs?
      I didn't get this.

      MPGW is already configured with an AAA policy 

              But we already have one MPGW configured with AAA policy and below is the configuration.

    1. Identity Extraction:  "Extract identity from the Subject DN of the TLS certificate from the connection peer" and "Token extracted from message"  with XPath expression
    2. Authentication: Pass identity token to authorization
    3. Authorization:  the Custom URL field, we specified the path to an XSLT file. This XSLT uses  " dp:auth-info('ssl-client-subject', 'ldap-strict')" to get details of the cert and to perform authorization using  an XML document that includes a specific ID from the request and its corresponding signature

    What I don't understand is why there is a  AAA policy? If we can get the details using " dp:auth-info('ssl-client-subject', 'ldap-strict')" and do all the authorization using single XSLT and maintaining XML with details like signature and ID's coming in the request why would he configured AAA policy by passing XSLT ?

    Regarding the latest requirement we've received -  Extract the certificate's thumbprint and subject of the Incoming certificate are checked against the defined certificate for the BID in the request. We need to match for the client to be authorized - here's what I've been considering:

    I plan to use service variables to extract the required  details like fingerprint and subject from the incoming connection. Then, by writing XSLT, we can perform the validation based on the certificate's fingerprint (thumbprint) and subject. I believe I should prepare and configure an XML file that maps each BID to its expected fingerprint and subject, which can then be used for validation.

    However, considering that the existing MPGW is already configured with an AAA policy, I'm unsure whether this approach is valid or the most appropriate. Could you please advise on the best practice or confirm if this method is compatible with the current setup?



    ------------------------------
    Krishna
    ------------------------------



  • 4.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Thu May 29, 2025 09:33 AM

    I see.  You've inherited a configuration and now required to change it.

    With that said, however, since you are managing (or planning to manage) each client certificate in the validation credential in a Mutual TLS setup, for it to continue on to the service policy, which includes the AAA policy, it generally means the certificate matched.  You can match the certificate exactly if you set the validation credential to match the exact certificate, and then non-clients will be rejected  prior to execution of the service policy.   This prevents the need to validate and authenticate in the policy, as it will be done via the validation credential configuration.

    The question now is:   Does client validation on the exact certificate mean the client is authorized, or must the client also be matched to a BID? (I'm not immediate coming up with what BID means here, though, this may not be as important to the goal).



    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------



  • 5.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 01:36 AM

    Hello Joseph,

    Yes, we currently have one AAA policy that was developed by a former employee. We are now trying to understand how to fulfill a new requirement, as both policies appear to be similar with only minor differences.

    As you mentioned, configuring validation credentials to match the exact certificate is sufficient for verifying the client.

    For the remaining validation steps, such as checking the BID and fingerprint, we can handle those using XSLT and an XML file, as I mentioned earlier.

    Given that, why do we need an AAA policy to perform the same validations?

    To clarify, we do need to authenticate based on the BID-that requirement is certain.



    ------------------------------
    Krishna
    ------------------------------



  • 6.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 02:14 AM

    The AAA policy ensures that you end up writing less code in XSLT and leverage the built-in validation and mechanics of DataPower. Of course you can completely get rid of AAA policy and end up doing everything in XSLT but that will be a sizable coding effort. 

    Usually the said requirement is implemented slightly differently. In AAA policy, the 'identity extraction' phase will extract client certificate and validate it. It guarantees that client cert is valid and all checks and balances associated with certificate are valid. Once that is done, the certificate information is trusted (as far as authentication is concerned) and the DN of certificate (or for that matter it can be any other field) is typically used for authorization. In this phase you will have a custom XML file that uses XACML to compare incoming DN with a predefined whitelisted set of DNs (and of course resource URIs). If there is a match the authorization step is deemed successful.

    In this example there is no specific coding needed. The validation of cert and extraction of DN is handled just by configuration in AAA policy.

    Hope this helps.



    ------------------------------
    Ajitabh Sharma
    ------------------------------



  • 7.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 02:48 AM

    Hello Ajitabh,

    If we configure an FSH (Front Side Handler) with a server profile that includes both identity and validation credentials, the incoming client certificate will already be validated (or rejected) during the TLS handshake phase. In that case, why do we still need to implement an AAA policy to perform the same certificate validation?

    My understanding is that we can extract the certificate details (like Subject and Thumbprint) directly in XSLT and compare them against a reference XML file containing the expected values for multiple clients.

    So, can we skip either the TLS validation (via validation credentials in the server profile) or the AAA policy, since they both seem to be performing similar validation?

    Apologies if this sounds basic - I'm still learning the internals of how DataPower handles client certificate validation.



    ------------------------------
    Krishna
    ------------------------------



  • 8.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 09:29 AM

    >>  why do we need an AAA policy to perform the same validations?

    Technically no, but as Ajitabh Sharma stated, you can ideally take advantage of a number of features the AAA policy provides.  Though you shouldn't need to do much of anything in the authentication step, you'll still need a custom XSLT in the authorization stage.  I remain a strong proponent of configuration-rather-than-code in DataPower wherever possible.   By using the AAA policy, you also get to take advantage of authentication/authorization mapping, post-processing, and better more meaningful error handling with far less code.  

    >> we do need to authenticate based on the BID-that requirement is certain.

    "authenticate" or "authorize"?  It seems like authentication is taken care of by the validation credential and exact match on the certificate.   



    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------



  • 9.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 10:00 AM

    Hello Joseph,

    The BID is intended for authorization. We plan to gather a list of expected BIDs, certificate thumbprints, or subjects (this is still to be finalized), and store them in an XML file.

    Could you please guide me on the required configurations in IBM DataPower if we want to:

    Authenticate the client based on their certificate identity, and

    Authorize them based on the value of a specific tag in the request payload (i.e., the BID)?



    ------------------------------
    Krishna
    ------------------------------



  • 10.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 02:21 PM

    It sounds like authentication is taken care of by the validation credential.

    If something in the message payload (BID) has to play a part in authorization, you have a couple of choices, and this is a matter of preference for you.

    Use AAA Identity extract step to extract the certificate information and the BID from the message (Token extracted from message).  That is, you can use multiple selections and get what you need from by configuration only.  In the Authentication step, you pass it to the authorization phase.  In the "Credential Mapping" step, this could be a place to map the BID to the subject.  Look up documents on the use of the "AAA Information File", where you can maintain the mapping, thus treating the BID as part of authentication.  If you go this route, you can skip authorization.  However, if not, you could extract the BID as the "resource" and then map with an "AAA Information File" in the "Resource Mapping" step.  This all depends upon if you consider the BID as a resource request, which may not be the case.  Do note:   You can still use an "AAA Information File" in the "Authorization" step.  It's whatever you choose.  I still have no idea what the BID is, but, apply the logic semantically based upon it being part of the identity for authentication, a resource, or part of authorization.  In any of the many steps, you have a "Custom template" option where you simply apply XSLT as well.   The "Post Processing" can then be used to apply some AAA transform to alter the request message in some way to let a back-end application know DataPower applied the AAA.   The back-end could be designed to reject any request not having the DataPower "stamp of approval".

    If the BID is just a simple mapping to the subject of the client cert, then using an XSLT in place of the AAA policy may be sufficient, provided you don't get caught up in a coding quagmire.

    Maybe if I knew what the BID is, maybe another logical process could be explained, but, it is ultimately your choice.  

    One thing to keep in mind though.  Someone other than you may one day have to figure out what's happening here.   This is why I recommend keeping with configuration over coding where practicable, because when using configuration, even with using custom templates, you are somewhat forced to keep the XSLT/GWS small and to the point.   There is little more irritating than to have to dig through hundreds (and I've seen thousands) of lines of code to figure out what is going on.  Unless that code is very well documented (and I very rarely find code that is), it can be a major problem.



    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------



  • 11.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 02:50 PM

    Dear Joseph,

    At this moment, I'm also not fully aware of the exact role of the BID in the payload. From what I understand, it seems to be a code that identifies the client.

    This approach was requested by the client:

    We are expected to extract the thumbprint and subject from the incoming certificate, retrieve the BID from the request payload, and validate all three against an XML file that contains a list of expected BIDs along with their corresponding thumbprints and subjects.

    I will share more details on the exact meaning and purpose of the BID as soon as I receive clarification from the client.

    But I hope the information provided so far will be sufficient for you to guide me with a suitable approach.

    Thank you for your support!



    ------------------------------
    Krishna
    ------------------------------



  • 12.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted Fri May 30, 2025 06:36 PM

    Krishna,

    So, I have assumed you knew how, but was asking more about approach with respect to the AAA policy or by just using an XSLT.   

    Tell me what you don't exactly know how to do and we can help you.



    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------



  • 13.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 30 days ago
    Edited by Krishna 29 days ago

    Dear Joseph,

    I have created an HTTP Front Side Handler (FSH) with a server profile that includes client certificate identification and validation. In the MPGW policy, I intended to use XSLT to extract:

    • The client certificate thumbprint using dp:get-cert-thumbprintsha1()

    • The certificate subject using dp:auth-info('ssl-client-subject', 'ldap-strict')

    However, when I send a request to the MPGW with a client certificate, the function dp:get-cert-thumbprintsha1() does not return the thumbprint of the client certificate.

    Could you please advise how to properly retrieve the thumbprint of the client certificate when it hits the MPGW?



    ------------------------------
    Krishna
    ------------------------------



  • 14.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 28 days ago

    Hello Everyone,

    Kindly help how to get the thumbprint of the Incoming client certificate through XSLT?



    ------------------------------
    Krishna
    ------------------------------



  • 15.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 28 days ago

    You may have to share your actual code and exactly where it is configured in your policy. 

    I generally start with a dp:auth-info('ssl-client-cert'), and then use the dp:get-certXXX functions to extract the certificate information.  Just know that dp:auth-info('ssl-client-cert') returns a base64 encoded cert, so you'll need to use the proper cert: parameter in the other functions.



    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------



  • 16.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 28 days ago
    Edited by Krishna 28 days ago
      |   view attached

    Dear Joseph,

    I have attached  the relevant portion of the XSLT I'm using to extract the Subject and Thumbprint of the incoming client certificate. Could you please help fix it so that it correctly retrieves the thumbprint?

    Previously, I had tried the suggested expression dp:auth-info('ssl-client-cert'), but it didn't work as expected - I may have implemented it incorrectly.




    ------------------------------
    Krishna
    ------------------------------

    Attachment(s)

    txt
    get-details.txt   1 KB 1 version


  • 17.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 28 days ago

    >> Previously, I had tried the suggested expression dp:auth-info('ssl-client-cert'), but it didn't work as expected..

    What did it return?   It should return a base64 encoded certificate.  You then have to call the other functions to extract the information from it.



    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------



  • 18.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 28 days ago

    Yes, I did receive the base64-encoded certificate using dp:auth-info('ssl-client-cert'), but I wasn't able to process it further to retrieve the thumbprint. I couldn't figure out the correct extension function to use for extracting the thumbprint from the encoded certificate.


    with the below XSLT:

    <?xml version="1.0" encoding="UTF-8"?>
    <xsl:stylesheet version="1.0"
    xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:dp="http://www.datapower.com/extensions"
    xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
        exclude-result-prefixes="dp wsse"
        extension-element-prefixes="dp">
    <xsl:output method="xml"/>
    <xsl:template match="/">
    <xsl:variable name="certdetails" select="dp:auth-info('ssl-client-cert')" />
    <xsl:variable name="thumbprint" select="dp:get-cert-thumbprintsha1($certdetails:base64Cert)" />
    <xsl:message dp:priority="debug">Certdetails: 
    <xsl:value-of select="$certdetails"/>
    thumbprint:   
    <xsl:value-of select="$thumbprint"/>
    </xsl:message>
    </xsl:template>
    </xsl:stylesheet>



    Could you please help  on how to pass the encoded certificate to the appropriate function to get the thumbprint?



    ------------------------------
    Krishna
    ------------------------------



  • 19.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 28 days ago

    Hello Joseph,

    The following is giving me the thumbprint. Is there any other approach, or is this okay to follow?

    <xsl:variable name="cert" select="dp:auth-info('ssl-client-cert')" />

    <xsl:variable name="b64-thumbprint" select="dp:get-cert-thumbprintsha1(concat('cert:', $cert))" />

        <xsl:variable name="hex-thumbprint" select="conv:base64ToHex($b64-thumbprint, 'ERROR')" />



    ------------------------------
    Krishna
    ------------------------------



  • 20.  RE: How to extract Thumbprint and Subject to Validate Incoming Client Certificate

    Posted 28 days ago

    Yes.  You're on the right track now.  You can get the subject with get-cert-subject(concat('cert:', $cert)).



    ------------------------------
    Joseph Morgan
    CEO - Independent
    ------------------------------