Practical DataPower: A Shared HTTPS Authorization Proxy


Executive Summary

Improving endpoint security is a great justification for introducing a DataPower environment to the enterprise. Currently, HTTPS is the standard transport for communication between two endpoints. Therefore, a vital service that DataPower hosts is an endpoint that performs security services on client connections and then forwards the request to the backend for further processing. Pretty much every DataPower environment has a form of this service.

The problem is that this is usually the first service that a new team implements, is the most visible and is very difficult to adjust once put into production. A new team may not have the experience to understand the pain lurking down the road of their early decision. To help design this type of service, this article implements an HTTPS security service that is flexible, dynamic and secure. It validates client certificates for the endpoint they request while not falling into the trap of installing client certificates directly on the appliance. Not installing client certificates provides a substantial maintenance cost savings, as these certificates do not need to be renewed and don’t cause outages when they aren’t. The entire configuration is available for download on GitHub.

If your current shared proxy is the source of outages, project delays or has become a certificate maintenance nightmare, then read on.


The most common reason for bringing in an IBM DataPower Gateway environment is for security purposes. The device is top-notch in protocol support and the diversity of configuration options can support most requirements. In the security pattern, DataPower authenticates and authorizes an inbound connection and routes the validated connection to downstream services for further processing. The most common implementation of this pattern is as a shared HTTPS Proxy. Clients provide identification with an X509 certificate and requests access to a resource via the URL. It is then up to DataPower to determine if this client is allowed access. DataPower becomes the enterprise gatekeeper for endpoint security.

It is common for every DataPower customer to implement this system on their own. Worse, being a core platform requirement, it is the first service ever developed and hosted. It’s the first, it’s the most important, and it will live in the environment forever. This is a difficult task to give a new team and have them get it right the first time.

Part of this Practical DataPower series, this article implements an end-to-end HTTPS Authorization Proxy. This proxy is a shared service, used by all clients in the enterprise that want backend service access. It is a single authorization endpoint. We’ll discuss these benefits in the next section.

Sole Authorization Decision Benefits

When DataPower becomes the sole authentication and authorization point for service access, many messes are avoided:

  1. Some of the mess of enterprise certificate management is avoided. What cert is installed where? When does it expire? Who is using it?  Where are all the copies? Did we miss one? All of these questions need answers and they cost time and money every year. Expecting every platform to keep track of this information is naïve.
    • An exception is if your enterprise allows self-signed client certificates, but many enterprises don’t allow them.
    • Enterprises are starting to realize that certificates have an ongoing maintenance cost beyond development. The decisions of the past in placing all certificates directly into client and server validation keystores is taking a toll as they being to expire and cause outages.
      •  It’s not a problem with certificate technology. We just need to be smarter about how they are used.
  2. The mess of enterprise service access control management. What clients can access what services? Where are the access list stored? If every technology is responsible for maintaining an independent list, then there is a risk of it not being completely secured and a critical endpoint is left open for attacks.
  3. The mess of auditing the enterprise security policy. Your service whitelists, supported ciphers and allowed certificates are all in one spot.
  4. The mess of ensuring all your technology subject matter experts understand security best practices. New exploits are being released faster than ever. When the next heartbleed attack is released, how do you ensure that your technologies are patched and safe?
    • It’s always easier to work with a single team than it is to try to hold parties accountable throughout the enterprise.

Being the single point in the enterprise for a security decision is not one that can be made lightly. If the process surrounding change is too slow, then every project will be impacted and projects will start looking for loopholes. Therefore, we need to ensure that this solution is stable, quick to update and reliable. Adding new services can not impact existing services and turnaround to modify endpoints cannot not take days, but minutes.

Service Requirements

The HTTPS Authorization proxy service is built to meet the following requirements:

  • The service authenticates all HTTPS service consumers.
  • Clients must present an SSL certificate for identification.
    • Those that do not will be rejected.
  • Clients are authorized by the following configuration tuple:  {certificate, [certificate issuer], [environment], URL}.
    • [issuer] and [environment] are optional, based on the specific enterprise requirement.
    • certificate and url are always required.
  • A service’s whitelist should allow multiple certificates signed by different certificate authorities.
    • Endpoints exposed to vendors will need this as they always use different certificate authorities for their certs.
  • The whitelist configuration should be portable between environments.
    • For example, the same physical file should be used in DEV as in QA as in pre-prod as in PROD.
  • Clients can be authenticated by verifying certificate’s distinguished name (DN) or the certificate’s common name (CN).
    • DN provides more security at the cost of being susceptible to outages when the client certificate is renewed and some of the attributes change (usually by accident) (i.e.: city).
    •  CN validation ignores the country (CA), state (ST), locality/city (L), organization (O) and organization unit (OU) fields of the certificate.
  • The endpoint should only accept TLS 1.1 or TLS 1.2 connections.
  • The request payload can be either JSON or XML.
  • The service should not inspect the payload of the incoming message to make routing or authorization decisions.
  • Authorized requests are forwarded to a service specific URL for subsequent processing.
    • Unauthorized requests are rejected.
      • In non-production environments, a detailed error message should be logged and returned to the client.
        • This allows projects to self-heal bad requests without involving DataPower resources to check logs.
      • In production environments, a detailed error message should be logged but a generic error message should be returned to the client.
        • In production, it is important to contain information leaking. We shouldn’t tell a potential hacker what is wrong with their request message.
        •  An assigned resource and process should be available to check the logs and debug.
  • When an error occurs, JSON clients should receive a JSON error message and XML clients should receive an XML error message.
  • DataPower will define a platform standard URI format for all request messages.
    • Messages that do not meet this URI format will be rejected.
  • Adding and Removing authorized certificates and servers should not require DataPower object configuration changes.
    • Changes should be contained to whitelist file updates.
  • DataPower will provide two potential matches of an incoming URI against the whitelist
  • The first match is for the entire URI. This is called the specific match. For example: /dp/EchoService/echo.
    • If a configuration exists for this match, then the next match’s result is ignored.
    • The second match is for the first two components of the URI. This is called the generic match. For example: an entry in the whitelist for /dp/EchoService that matches /dp/EchoService/reverse when the specific match does not exist.
      • Allowing a generic match helps to reduce the size of the whitelist when a group of URIs share the same allowable list of certificates. If the generic match didn’t exist, then a service with 100 endpoints would require 100 copy-paste entries becoming immediately unmaintainable.
  • The whitelist for all services should not be contained in a single shared file.
    • A single location makes it too easy to typo an update and impact unrelated services during a change.
    • At the same time, requiring unique files becomes unmanageable, so a delicate balance needs to be achieved.


All of the project artifacts are available on GitHub as part of the ‘Practical DataPower’ repository. This repository hosts all the XSLT and DataPower configuration along with a domain export that can be easily imported.

The domain export can be downloaded from GitHub.

The OSC_PD_SSL_Service domain can be imported from the Control Panel, via the Import Configuration wizard. By default it listens on port 9193 of all interfaces.

Implementation Details

The service is an XML Firewall but this does not restrict the incoming request to XML. A multi-protocol gateway could have been used, but unlike the stub service, this service doesn’t benefit from being provided over other transports. It is only relevant to HTTPS client authentication.

Requests to DataPower require the following URI format:

/dp/[service-config-id]/[0..N additional segments]/

      • /dp/: This easily identifies that the URL is referring to a DataPower endpoint. This becomes helpful in mutli-technology debugging sessions when it is difficult to tell where clients are sending transactions and are sometimes given incorrect endpoints. If someone gives you a URL saying they having a connectivity error to DataPower and it doesn’t start with ‘/dp/’ you know it’s wrong.
      • /[service-config-id]/ : This segment decides the configuration.xml file to load that holds the whitelist and routing information used to authorize the request. DataPower will load the file ‘local:///[service-config-id]/config.xml‘. This allows separation between unrelated services, but services that share the config-id can be grouped together.
        • service-config-id’s can be anything. They could be numeric or they could be random.
          • I suggest using either the domain that the request is forwarded to, or the name of the project the endpoint relates to. Hard to remember URIs make typos easy and the obfuscation justification is thin.
      •  /[0..N additional segments]/ : These can be used to provide finer grain security over the incoming request, and to differentiate request types when forwarded on for subsequent processing.
        • For example: /dp/EchoService/echo or /dp/EchoService/echo/backwards.

The firewall will first attempt to load the configuration for the specific URI. For example ‘/dp/EchoService/echo/backwards’.  If a configuration can’t be found, then it will try the generic URI. The generic URI is the combination of the first two components. For example: ‘/dp/EchoService’. If the configruation still can’t be loaded, then an error is returned.

XML Whitelist Format

The following is the format for the XML whitelist. You can also view the sample config.xml included in the domain as a reference.

  • <services>: The container element for the entire XML document.
    • <service>: The definition of a service configuration.
      • @url : The URI for the service configuration.
      • @env : The optional DataPower environment for the configuration (DEV/QA/PROD etc).
      • <allow>: A 0..N list of allowed issuer/certificate pairs
        • @issuer: The optional certificate authority that signed the client certificate.
        • <dn>: The complete distinguished name of the client certificate that is allowed access.
          •   Example: ‘<dn>/C=CA/ST=Ontario/L=Toronto/O=Orange Specs Incorporated/OU=Consulting/</dn>’
            • The slash-delimited format of this string is provided by DataPower in an AAA.
        • <cn>: The common name of the client certificate allowed access to the service.
          • Example: <cn></cn>’
      • <endpoint>: The container element for the backend hostname and port that an authorized request will be forwarded to. The intention is for this to be a port hosted on the DataPower device.
        • <hostname> : The hostname of the backend service.
        • <port>: The port of the backend service.

An XSD for the Whitelist XML format is also supplied.

XML Firewall

This section describes the non-default configuration options needed on the XML Firewall object.

Firewall Type: Dynamic Backend

The backend service is dynamically set by the routing.xsl transformation based on the endpoint hostname and port from the config.xml.

Request Type: Non-XML

DataPower will treat the request message as binary, meaning that the appliance won’t attempt to validate or touch it in any way.

Response Type: Non-XML

DataPower will treat the response message as binary, meaning that the appliance won’t attempt to validate or touch it in any way.

Process messages whose body is empty: ON

This will allow HTTP GETs to flow through the proxy.

SSL Type: Server Profile

This uses the preferred ‘Server Profile’ object which superseded the SSL Proxy Profile object in firmware 7. If there was a requirement to host multiple SSL configurations from the same port, then we could have used an Server SNI Profile. The tradeoff would be that all clients would have to support SNI, which is not true in a large enterprise.

SSL Server Profile: SSL-Service-Server-Profile (see below)

SSL Configuration

This section describes the SSL Server Profile configuration.


      • Enable SSL version 3 – OFF
      • Enable TLS version 1.0 – OFF
      • Enable TLS version 1.1 – ON
      • Enable TLS version 1.2 – ON

The service should only allow TLS 1.1 & 1.2 handshakes, so the other options are disabled.

Ciphers: Left as defaults. This is where in the future, if a cipher is found to be vulnerable, you can remove it from the list. Direction over acceptable ciphers should be obtained from your enterprise security team. If not, the defaults are ok.

Identification Credentials: SSLService-Server-ID-Cred

This is the public certificate and private key pair the DataPower server sends to clients.

Request Client Authentication: ON

In the TLS standard, client authentication is not required. For our solution though, we need the client to identify themselves, so we turn this on.

Require Client Authentication: ON

From the above option, the client is merely requested to represent themselves. They can still choose to not present a certificate. With this option enabled, if the client doesn’t present one, DataPower will close the connection.

Validate Client Certificate: ON

DataPower will validate the presented client certificate against the validation credentials object specified later in the config. If this was turned off, then DataPower would accept any certificate. If the presented certificate is not in this validation credential object, then DataPower will close the connection.

Send client authentication CA list: OFF

When enabled, this will send a list of the certificate distinguished names from the validation credentials. In theory, this would allow a consumer to browse the list, identify a common signer of a certificate they have and respond with it. In the real world, clients are statically configured to present a single certificate and presenting the list is needless chatter. We’ll disable it.

Validation Credentials: SSLService-ValCred (see below)

Validation Credentials

This section describes validation credential object configuration.

Certificate List: This is the list of SSL certificates that the endpoint will accept during TLS negotiation.

It is very important to understand the types of certificates that should installed here:

      • Self-Signed Certificates
      • Certificate signer certificates (example: Verisign Certificate Authority, or intermediate issuer certificates

A specific client cert signed by a certificate authority should NOT be installed into the environment. This practice is known an SSL Certificate Pinning and it comes with a large avoidable cost. The cost is in maintaining and renewing these client certificates when they expire at inconvenient dates in the future. Each certificate has its own renewal process and production installation timing. If you pin and the client certificate changes, they won’t be able to connect and the result is an outage.

We mitigate the risk of accepting certificates at the signer level through the use of a DataPower AAA object and verifying the CN/DN in the whitelist contained in the config.xml.

Certificate Validation Mode: Full Certificate Chain Checking (PKIX)

DataPower will verify that the client certificate is either matched exactly in the certificate list, or that a complete signer chain from the incoming cert all the way to the root certificate authority can be established. Given that this endpoint is our primary method for verifying client identity, we should take every measure to ensure that it is fully validated.

This setting implies that we have a solid understanding of the signers that the clients use. We need to include all the intermediates and root signer certificates. If we don’t, DataPower will reject the connection.

Check Dates: ON

DataPower will verify that the current date is between the certificates notBefore and notAfter dates. If you turn this off, then you are susceptible to accepting expired certificates in your environment. An implied requirement of checking dates is that your data power appliance needs to be configured to use a reliable NTP server.

This completes the firewall configuration and TLS settings. Next we’ll talk about the Processing Policy Rules.

Request Rule

This rule services all requests for the proxy. It is a ‘Client To Server’ Rule with 4 configured actions:

      1. A match action that accepts everything.
      2. An AAA Action that authenticates and authorizes a client connection.
      3. An XSLT Transform action that routes the request to the appropriate backend.
        • Input: NULL
        • Transform File: ‘routing.xsl
        • Output: NULL
      4. A Result action that sends the request to the backend.
        • Input: INPUT
        • Output: OUTPUT


The AAA object is broken down in 6 parts: Extract Identity (EI), Authenticate (AU), Map Credentials (MC), Map Resource (MR), Authorize (AZ) and Post Processing (PP). For our solution, the most important are the EI and AZ phases.

(EI) Define how to extract a user’s identity from an incoming request: Subject DN of SSL certificate from connection peer

DataPower will extract the distinguished name from the client certificate and use it as the client identity for the next stage of processing.

(AU) Define how to authenticate the user: Pass identity token to authorization phase

We’ve already authenticated that the user presented a valid certificate allowed by the validation credentials. We don’t need any additional authentication of the information at this point, so we tell the AAA to just pass along the extracted identity (the certificate DN).

(MC) Define how to map credentials: None

This stage would allow us to map the contents of the certificate into a different format if needed. For Example if the client presented ‘/C=CA/ST=Ontario/L=Toronto/O=Orange Specs Incorporated/OU=Consulting/’ we could extract the CN as the subsequent identity of the client. We could also decide to map a list of allowed certificates into a credential that represents the service, ie ‘EchoService’. This ‘EchoService’ token would then be referenced elsewhere in the AAA.

We don’t use this option, as it would introduce an intermediary into the relationship between certificate DN and service access in our whitelist config.xml. We want the config.xml to be authoritative over the specific certificates it allows. We don’t want to have to look up this additional mapping in multiple locations.

(ER) Define how to extract the resources: URL sent by client

Our whitelist is dependent on the client URL, so we check that box.

(MR) Define how to map resources: None.

We want the pristine URL from the client, so we don’t map it.

(AZ) Define how to authorize a request: Custom template.

DataPower will run the aaa-authorize.xsl to determine if the client is authorized to access the service they requested.

(PP) Post Processing –  All post processing is not needed and disabled.

XSLT: environment.xsl

This is a small XSLT template that returns the current environment that represents the  DataPower appliance. Depending on the actual topology, it could be determined by source IP address or even included as a header by the requesting application. In our case, it’s hardcoded to return the string ‘DEV’. If the device was meant to represent production, then the XSLT on that production device would return ‘PROD’.

XSLT: aaa-authorize.xsl

This is responsible for making the authorization decision based on the certificate and URL requested by the client.


      1. Stores the current environment in a  variable named ‘dp_env’ by calling the template stored in environment.xsl.
      2. Defines the request configuration id (req_confg_id) as the 2nd component of the client requests’ URI.
      3. Loads ‘local://./[req-config-id]/config.xml’ file contents into ‘config_file_xml’.
      4. Stores the certificate DN into ‘client_dn’ and extracts the CN into ‘client_cn’.
      5. Converts the client certificate issuer DN into an identifier by calling the ‘getIssuerIdentifier’ template.
        1. Using an identifier makes updating the config.xml cleaner by avoiding pasting repetitious long signer DNs.
        2. This template can be extended in the future to do a more thorough job of associated signer DN’s to identifiers and can be as specific or general as needed.
      6.  Logs all the properties at the debug level.
      7. Calls ‘getMatchStatusCode’ twice. Once for the specific URL and once for the generic URL.
        1. During matching, the optional ‘env’ and ‘issuer’ attributes are ignored if the config.xml doesn’t specify them.
        2. ‘getMatchStatusCode’ attempts to verify that a certificate is allowed access to the requested URI.
          1. Code 500 if the config.xml couldn’t be loaded
          2. Code 404.1 if the URL could not be found in the config.xml
          3. Code 404.2 if the URL was found but the environment didn’t match
          4. Code 404. 3 if the URL and environment matched but the signer did not
          5. Code 403 if the URL, environment and signer matched but neither the CN or DN matched.
          6. Code 200 if a match was found.
      8. Determines the overall service status code by inspecting the status code from the two getMatchStatusCode calls. The specific match code is returned unless it returned a 401.1 (not found). In that case, the generic code is used as it’s an error that is more specific.
        1. Code 400 if no client cert was presented (impossible to occur based on our Server Profile config but good to have anyway for completeness).
        2. Code 400.1 if the URI didn’t start with ‘/dp/’
        3. Otherwise it uses the codes as above.
      9. Create the detailed status message that represents the status code, including as much detail as possible.
      10. Check the overall status code
        1. If the code is 200, then emit the snippet ‘<approved/>’. This special snippet tells the AAA action to allow the transaction.
        2. If the code isn’t 200, reject the transaction by emitting ‘<declined>..reason..</declined>’. The reason is the status message that was calculated above. This status message is not returned to the client, but rather is stored by DataPower in ‘var://service/error-message’. This variable is used in ‘processError.xsl’.

Once the AAA is complete and has authorized the request, the request rule moves along to the next action, the transform referencing ‘routing.xsl’.

XSLT: routing.xsl

This is responsible for configuring the XML firewall dynamic routing variables to forward the authorized request to the subsequent DataPower service for processing.


      1. Loads the config.xml based on the URI.
      2. Attempts to load the ‘/services/service’ for the specific URI and the generic URI.
        1. Note that it doesn’t need to do any certificate checking, we did that in the previous step.
      3. Use the DataPower function dp:set-target to configure the outbound URL.
        1. If the specific service URI is found, use it,
        2. If the generic service URI is found, use it.
        3. If neither is found, emit a dp:reject. The reason will be processed in the processError.xsl.
      4.  Log the result at the debug level.

It should be noted that routing the transaction uses HTTP and not HTTPs. There’s no reason to perform another TLS handshake when chaining together DataPower services inside the appliance.

With the routing information set, the transaction flows to the result node and off to the backend service.

Response Rule

This rule services all responses from the backend service for the proxy. It is a ‘Server to Client’ Rule with 2 configured actions:

      • A match action that matches everything
      • A result action that returns the response message.

In lieu of creating a response rule, we could have set the XML Firewall’s response type to Pass-through. It’s a personal preference. Having an explicit request and response rule makes the solution more complete and gives a future hook to expand the service if needed.

Error Rule

This rule handles all errors that occur during the proxy. This includes AAA <declined>’s along with errors when trying to contact the backend service.  It is an error rule with 3 configured actions:

      • A match action that matches all error codes
      • A transform action
      • A conditional action with two sub actions that either convert JSONx to JSON or pass-through XML.
        • When ‘PIPE′ contains a JSONX message (/*[namespace-uri()=’’] is true):
          • Run a transform action that will convert the JSONX into JSON
          • Input: ‘PIPE’
          • Transform File: ‘store:///jsonx2json.xsl’
          • Output: OUTPUT
        • Otherwise (1=1)
          • Run a result action and return the XML error back to the client
          • Input: ‘PIPE’
          • Output: OUTPUT

XSLT: processError.xsl

This is used by the error rule to output an environment appropriate error to the client. It also takes in account if the initial request was JSON or XML and emits the same type of message back to the client.

This XSLT:

      1. Saves the request’s original content type into ‘orig_content_type’.
      2. Determines the current environment.
      3. Formats the error message
        1. If the environment is not ‘PROD’
          1. If the error sub-code is rejected by AAA (error codes: ‘0x01d30002’ or ‘0x01d30001’), we output the error message.
          2. Else we tack on the selected outbound URL to the error message
        2. If the environment is PROD, we return a generic error message payload back to the client.
      4. Inspect the original content type to determine the type of error message to emit.
        1. If it contains the word ‘json’, then we emit a JSONX message
        2. Else we emit the error in XML.

This completes the walk-through of the DataPower configuration. The next sections discuss testing the service with the sample configuration that is included in the domain.

Test Certificates

To test this service, we need certificates that are signed by a certificate authority and ones that are self-signed. The following test certificates are stored on GitHub to facilitate testing in the /tls/ directory:

      • client-self-signed : contains self-signed test client certificates:
          • C=CA, ST=Ontario, L=Toronto, O=Orange Specs Incorporated, OU=Consulting,
            • This certificate is matched via DN in the sample config.
          • C=CA, ST=Ontario, L=Toronto, O=Orange Specs Incorporated, OU=Consulting,
            • This certificate is matchd via CN in the sample config.
          • C=CA, ST=Ontario, L=Toronto, O=Orange Specs Incorporated, OU=Consulting,
            • This certificate is never referenced in the sample config and can be used to test rejection behaviour.
          • C=CA, ST=Ontario, L=Toronto, O=Orange Specs Incorporated, OU=Consulting,
            • This certificate is used in signer-chain testing.
          • C=CA, ST=Ontario, L=Toronto, O=Orange Specs Incorporated, OU=Consulting,
            • This certificate is used to verify expiry scenarios.
      • orangspecs-ca: an openSSL certificate authority configuration that can be used to sign certificates.
        • The CA certificate uses the DN:
          • C=CA, ST=Ontario, L=Toronto, O=Orange Specs Incorporated, OU=Orange Specs Incorporated SSL Test CA, CN=Orange Specs Incorporated SSL Test Root CA
        • The CA includes an intermediate signer:
          • /C=CA/ST=Ontario/O=Orange Specs Incorporated/OU=Orange Specs Incorporated SSL Test CA/CN=Orange Specs Incorporated SSL Test Intermediate CA
      • client-orangespecs-signed: Certificates signed by the orangespecs SSL Test certificate authority from above.
          • C=CA, ST=Ontario, L=Toronto, O=Orange Specs Incorporated, OU=Consulting,
            • Notice that this client=4’s DN is identical to the self-signed DN. This is intentional and is used to prove that the ‘signer’ attribute filters properly.
      • ssl_service-server: The key/cert pair used in the identification credentials for the TLS server profile.

Test Validation Credentials

In order for self-signed certificates to be accepted, they have to be uploaded to the device. We use the cert:// directory instead of pubcert:// or sharedcert:// because these certs have no value to other domains in the environment and shouldn’t be shared. These self-signed certs also have to be added to the validation credentials. If they are not added then the TLS handshake will be rejected and a verification error message written to the log.

For ‘Orange Specs SSL Test Intermediate CA’ signed certificates to be accepted, the ‘orangespecs-intermediate-ca.cert‘ and the root CA ‘orangespecs-ca.cert‘ need to be uploaded and added to the validation credentials.

Test Configuration

A set of DHC Test cases are supplied and can be downloaded here. These test cases correspond with the test configuration for the ‘EchoService’, an endpoint that responds with the input request message. The Echo Service domain can be downloaded here. By default it listens for HTTP requests on This keeps the transaction within the appliance.

The SSL Service exposes endpoints:

      • ‘/dp/EchoService/dev-ss12-os4’
        • This endpoint accepts self-signed client-1/client-2 and orangespecs signed client-4.
          • client-1 is accepted via full DN
          • client-2 is accepted via CN
        • Presenting self-signed client-3 will result in a bad authentication certificate error, as 3 is not in the SSL Server’s validation credentials.
        • Presenting self-signed client-4 will result in an error as only the orangespecs signed version of client-4 is allowed access.
      • ‘/dp/EchoService/dev-os4’
        • This endpoint only accepts the orangespecs signed client-4 certificate.
      • ‘/dp/EchoService/no-env-ss12’
        • This endpoint only accepts self-signed client-1 and client-2.
        • This endpoint shows that you are not required to specify and environment variable in the config.xml.
      • ‘/dp/EchoService/no-issuer-check-ss124’
        • This endpoint accepts self signed client-1, client-2, client-4 and orangespecs signed client-4.
        • There’s no issuer specified in the config.xml, so the certificate issuer is ignored and both versions of client-4 are allowed access.

These endpoints are low level examples testing functionality of the SSL service. In reality, you would expose real service endpoints such as ‘/dp/EchoService/echo’.

In DHC, when you would like to change the certificate you are presenting, you need to close and restart Chrome. The certificate selection box will re-appear.

Future Considerations

The following are ideas on how the service can be expanded in the future:

      • SOAP clients would prefer to receive the error XML packaged in a SOAP fault.
        • This could be accomplished by calling an ‘isSOAP’ attribute to the whitelist’s Service definition.
      • The whitelist XML files could be located off-device accessible from an HTTP server and cached by DataPower.
        • Updates could then be made independently of the DataPower team.
      • Modifications to the whitelist could be scripted.
        • This would remove concern over fat-finger updates.
        • Input validation can be added to ensure that the change is valid.
      • In any enterprise, there will be clients that cannot connect with TLS 1.2, cannot present a certificate or demand IP address based authentication.
        • In these insecure cases, a separate port and XML firewall should be created to authenticate them.
        • The wrong answer is to diminish the security of of the entire proxy to accommodate a single client.
          • Yet, this is the default path used by teams because it’s ‘faster’.
        • This also easily identifies clients that don’t meet corporate standards and require exemptions or future upgrade projects.
      • The current solution assumes that the {device, port} represents an environment for a request. The service can be made more flexible if the client requests themselves contain the requested environment.
        • This could be an ‘environment’ HTTP header, or an update to the URI format to include the requested environment.
        • The lack of environment header should signify a pre-prod or prod endpoint.
      • Support RESTful interfaces where object id’s are generally contained in the URI itself. Example: HTTP GET /account/0034231344
        • Could be accomplished by introducing a ‘*’ identifier that denotes the rest of the URI after that point should be ignored for whitelist purposes.


This HTTPS authorization proxy provides a solid foundation for your DataPower environment. It’s dynamic, straightforward and isn’t overly complex. Through the use of customization xml files (the config.xml) you can easily expand the endpoints exposed for client consumption. At the same time, the entire solution fits within a mere 200 lines of custom code. On top of that, you’ve alleviated yourself of having to manage and renew client certificates. It’s win-win.

In the Practical DataPower series, we show real world examples of the solutions the appliance can provide.

In this article, we went through every detail of the service and explained the logic behind it. You can download a domain export and the certificates from GitHub and play with it today. If you’ve been having problems with your current DataPower security solution, you might want to consider deprecating it and replacing it with this one.

About the Author

Dan Zrobok


Dan is the owner of Orange Specs Consulting, with over 14 years of experience working in enterprise systems integration. He is an advocate of the IBM DataPower Gateway platform and looks to improve environments that have embraced it. He also occasionally fights dragons with his three year old daughter Ruby, and newborn Clementine.

Share this Post