API Connect is a complete foundation for securing and managing access to existing service endpoints. For customers working with Bluemix a typical scenario is that the target application is running as an existing Bluemix application – for example a Node.js or Liberty application.

By routing requests for the application through API Connect you get fine grained control over which client applications are able to make requests to your application, transparently manage the client application’s association with your application as it evolves over multiple versions, and see detailed analytics about the use of your application by its various consumers.

A very common question from our customers is to ask how to secure the access to that Bluemix application so that you can guarantee that all access to that application flows through API Connect, and that the application endpoint can’t be invoked directly. In this post I will describe a range of techniques for enforcing that pattern.

Ensure all client applications must call your Bluemix app through API Connect and cannot make calls directly How do you ensure all client applications must call your Bluemix app through API Connect and cannot make calls directly?

There are three basic techniques for a Bluemix application to ensure that only permitted callers are able to invoke the application at runtime;

  1. Configure mutual TLS authentication so that incoming requests must present a trusted client certificate in order to establish a TCP connection to the application
  2. Enable Basic Authentication on the application, and the calling client specifies a trusted username/password in the Basic Auth header
  3. Define a custom HTTP header name and value that will be checked by the application code so that only callers who provide that header will be permitted to call the application

Each of these options has different pros and cons as described in the following table;

Approach Pros Cons
1. Mutual TLS authentication
  • Security is enforced at the network infrastructure level so unauthorized callers never reach the application tier at all
  • No changes are required to the application code or deployment
  • Can be used as a consistent approach across all types of runtime as it doesn’t rely on the functionality of the runtime itself
  • Ensures that the API Connect implementation will only connect to the correct server (if you enforce the “mutual” aspect) to prevent data being sent to a malicious spoofed target service
  • More complex to configure since it involves the configuration of a Bluemix custom domain, ownership and CNAME of a DNS name, and the generation/exchange of certificates
2. Basic Authentication
  • Widely supported by application runtimes
  • Often configured “declaratively” in the deployment of the application so no changes required in the actual code of the application
  • May not be suitable in cases where the application is already using the Basic Authentication mechanism to carry out a different form of authentication
  • Unauthorized requests reach the application runtime before they are denied, increasing load on the servers
3. Custom HTTP header
  • Widely supported by application runtimes
  • Quick and easy to implement by adding a couple of lines of application code
  • Typically requires custom coding changes to the application in order to implement (although it may be possible to abstract this from the real application logic through use of a servlet filter or similar)
  • Unauthorized requests reach the application runtime before they are denied, increasing load on the servers

The recommended approach is mutual TLS authentication (approach 1) as it enables you to deny unauthorized callers at the network level before the request ever reaches your application, and without making any changes to the application code itself, however it is slightly more complex to configure so the other two options may provide a sufficient level of security in situations a quick/easy solution is a higher priority than the strength of the enforcement.

The following sections describe how you would configure each of these techniques against your Bluemix application and how you configure API Connect to successfully authenticate with the secured application.

Note on IP whitelisting:

Another option which customers often enquire about is use of IP whitelisting to validate the incoming IP address of the request. In traditional IT deployments this has often provided an effective way of blocking unauthorized access at the network level, but the dynamic nature of cloud-hosted services mean that there is always the risk that the source IP address (or subnet) of an incoming request can change dynamically with little or no notice so this is not a technique which can be used reliably in the context of Bluemix and other hosted services.

Implementing the enforcement

The sections below give a high level overview of how to go about implementing each of the approaches described above. Click the link in each section to launch a detailed set of instructions that you can follow when configuring secure integration between your own Bluemix application and API Connect!

Approach 1: Mutual TLS authentication

Click here for a detailed set of instructions that follow the process of configuring TLS mutual authentication between API Connect and your Bluemix application.

  1. Configure the Bluemix application to present a server certificate, and require a specific client certificate to be presented
    1. Create a server certificate that will be presented by Bluemix, and a client certificate that will be presented by API Connect (and trusted by Bluemix)
    2. Create a custom domain in Bluemix and configure it to present the server certificate and trust the client certificate
    3. Add a route for the custom domain to your application
    4. Configure the DNS CNAME to route your domain name to Bluemix
    5. Validate that you cannot connect to the custom domain endpoint without providing the client certificate
    6. Prevent your application from being accessed over HTTP
  2. Configure API Connect to present the client certificate, and trust the server certificate
    1. Define a TLS profile in API Connect
    2. Select the TLS profile in the configuration of your Invoke/Proxy policy
    3. Stage/Publish the API and test the invocation

Approach 2: Basic Authentication

Click here for a detailed set of instructions that follow the process of Basic Authentication.

Configuring a Bluemix application to use Basic Authentication is achieved using different steps depending on which type of runtime your application is written in. In some cases Basic Authentication can be configured by making declarative changes to the deployment of the application itself, for example as described here for WebSphere Liberty, however for other runtimes it is necessary to make changes in the application code itself such as with Node.js here.

Having secured our application with Basic Auth we must then configure API Connect to present the appropriate “Authorization” header that will allow the incoming request to be authenticated. This could take one of two forms;

  1. Use a hardcoded credential that identifies the API implementation in API Connect
    1. Configure the Invoke policy with the username and password that will be used to call the Bluemix application
  2. If the caller of the API has presented an Authorization header then we can pass it through to the target service, which also has the advantage of passing the user’s context all the way to the backend service
    1. Configure the API in API Connect to require HTTP Basic Authentication
    2. Use the “set-variable” policy to pass the incoming user credentials onwards to the Bluemix application

Approach 3: Custom HTTP header

Click here for a detailed set of instructions that follow the process of configuring use of a custom HTTP header.

In this case the developer of the Bluemix application must define a custom HTTP header and fixed value that the caller must provide in order to be permitted to use the application – the enforcement of that header will be different depending on the specific runtime that the application is deployed in – but the basic steps are the same across every runtime;

  1. Configure the Bluemix application to require a specific HTTP header and value be presented by the caller
  2. Configure API in API Connect to set that HTTP header and value when it invokes the Bluemix application


In this post I have described the set of techniques for securing access to an existing Bluemix application with API Connect ranging from the recommended approach of TLS mutual authentication to some quick and easy options for preventing the casual snooper from circumventing API Connect to access your application endpoint.

The additional links above also provide detailed instructions that you can follow to secure your own Bluemix application with API Connect using any one of the three approaches described!

2 comments on"Three approaches to securing access to Bluemix applications with IBM API Connect"

  1. Very informative article !

  2. Jahanzaib Hanif March 16, 2018

    Thanks a lot for this post, do you have any article on how to connect back end on-prem API end point to IBM API connect cloud using Mutual TLS authentication.

Join The Discussion

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