IBM Integration Bus V9 - How to perform authorisation using SSL client certificates

 View Only
Fri May 15, 2020 07:48 AM

Philip Norton

IBM Integration Bus version 9.0 introduces the ability to propagate client SSL certificate information into a message flow. This article describes how information stored in the SSL certificate can be used to perform authorisation checks on the client. This enables an administrator to allow authenticated clients to access a subset of message flows. Topics covered include:

  • Enabling client certificate propagation
  • Accessing certificate information from within a message flow
  • Using certificate information for an LDAP authorisation check

Client Certificate Propagation

To ensure the client provides a certificate when they create an inbound connection client authentication must be enforced.

When using an HTTP Input node, the node wide listener is used by default and must have client authentication enabled. This is configured as follows:

mqsichangeproperties <node_name> -b httplistener -o HTTPSConnector -n clientAuth -v true

For SOAP Input nodes the embedded listener is used by default. Client authentication is enabled as follows:

mqsichangeproperties <node_name> -e <server_name> -o HTTPSConnector -n clientAuth -v true

Enabling this property requires that the correct SSL key store and trust store configuration are available to the Integration Bus. For details on how to configure SSL see the referenced article in the Resources section.

To ensure the client's certificate is propagated into the message flow the security profile set on the SOAP Input or HTTP Input node must have propagation enabled. To enable propagation on an existing Security Profile use this command:

mqsichangeproperties <node_name> -c SecurityProfiles -o <profile_name> -n propagation -v TRUE

If the Input node does not have a security profile configured the IBM supplied “Default Propagation” security profile should be selected.
This is configured from the BAR editor in the Integration Toolkit as shown in Figure 1.

 Figure 1. Default Propagation Security Profile


Accessing Certificate Information from a Message Flow

The certificate information is stored in the LocalEnvironment and can be accessed from LocalEnvironment.SOAP.Input.TransportSecurity.ClientAuth.Certificate or LocalEnvironment.HTTP.Input.TransportSecurity.ClientAuth.Certificate.

The full structure is shown in Figure 2.

Figure 2. Client Certificate Access from Local Environment

4 people like thisThe information can be accessed and manipulated, into the form required by the authorisation mechanism, using a transformation node such as Mapping, Compute or Java Compute. Code Listing 1 shows how the certificate subject field can be accessed and the attribute names removed to determine the user.

Code Listing 1. Java Code for Accessing the Client Certificate





String nodeType = localEnv.getFirstElementByPath("Destination").getFirstChild().getName();

MbElement transportSecurityElement = localEnv.getFirstElementByPath(nodeType+"/Input/TransportSecurity");

if (transportSecurityElement != null) {

MbElement clientAuthElement = transportSecurityElement.getFirstChild();

if (clientAuthElement != null) {

MbElement certificateElement = clientAuthElement.getFirstChild();

if (certificateElement != null && "Certificate".equals(certificateElement.getName())){

MbElement subjectElement = clientAuthElement.getFirstChild().getFirstChild().getNextSibling();

String subject = subjectElement.getValueAsString();

if (subject.indexOf(",") != -1) {

//Assume the subject is of the form CN=Philip Norton,OU=......

//(as set in the X509 certificate)

identity = subject.substring(subject.indexOf("CN=")+3, subject.indexOf(","));

} else {

//Assume the subject is of the form CN=Philip Norton

//(as set in the X509 certificate)

identity = subject.substring(subject.indexOf("CN=")+3);





//Store the manipulated identity in a new field in the LocalEnvironment

localEnv.createElementAsFirstChild(MbElement.TYPE_NAME_VALUE, "IdentityToAuthorise", identity);


  The example in Code Listing 1 stores the common Name (CN) attribute from the full Distinguished Name (DN) defined in the client certificate, into a new Local Environment field called IdentityToAuthorise.

Using Certificate Information for LDAP Authorisation

Once the required identity has been extracted from the client's certificate it can be used by a Security PEP node to perform authorisation. Add a new Security PEP node to the message flow and in the properties view set the Identity token type to 'Username' and the Identity token location to an XPath that resolves to the location of the extracted identity, as shown in Figure 3.

Figure 3. Setting the Identity Token Location on a Security PEP Node

The Security PEP requires a configured Security Profile, set using the BAR editor, to enable the specified identity to be authorized using a directory service. The Security Profile can be configured to authorize against an LDAP server using Integration Bus Explorer, an example is shown in Figure 4, or the mqsicreateconfigurableservice command, an example is shown below:

mqsicreateconfigurableservice <node_name> -c SecurityProfiles -o BluepagesProfile -n authorization,authorizationConfig,propagation -v "LDAP,\"ldap://,ou=memberlist,ou=ibmgroups,,x-uid_attr=cn\",TRUE"

This example uses LDAP to find a client by Common Name and authorizes them if they are a member of the group whose Common Name is UK.

For more information about configuring LDAP and configuring Integration Bus security see the referenced article in the Resources. section.


Figure 4. Configured Security Profile

  If the user is successfully authorized the input message will be propagated to the out terminal of the Security PEP node, otherwise the failure terminal will be fired.