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.
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;
- Configure mutual TLS authentication so that incoming requests must present a trusted client certificate in order to establish a TCP connection to the application
- Enable Basic Authentication on the application, and the calling client specifies a trusted username/password in the Basic Auth header
- 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;
|1. Mutual TLS authentication||
|2. Basic Authentication||
|3. Custom HTTP header||
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.
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.
- Configure the Bluemix application to present a server certificate, and require a specific client certificate to be presented
- 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)
- Create a custom domain in Bluemix and configure it to present the server certificate and trust the client certificate
- Add a route for the custom domain to your application
- Configure the DNS CNAME to route your domain name to Bluemix
- Validate that you cannot connect to the custom domain endpoint without providing the client certificate
- Prevent your application from being accessed over HTTP
- Configure API Connect to present the client certificate, and trust the server certificate
- Define a TLS profile in API Connect
- Select the TLS profile in the configuration of your Invoke/Proxy policy
- 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;
- Use a hardcoded credential that identifies the API implementation in API Connect
- Configure the Invoke policy with the username and password that will be used to call the Bluemix application
- 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
- Configure the API in API Connect to require HTTP Basic Authentication
- 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;
- Configure the Bluemix application to require a specific HTTP header and value be presented by the caller
- 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!