Monday, November 28, 2011

Video: Enabling OAuth to a Google JSON API using the Vordel API Gateway

OAuth is a very popular way to manage access to APIs. Amongst other things, it enables users to log into an application (which could be an application on a phone or tablet) and then that application calls lightweight APIs on their behalf. From a user's point of view, they accessed the application, and it all "just worked". They didn't have to enter any more passwords. From an implementation perspective, it's more complex of course. But an API Gateway makes it simple to call lightweight APIs using OAuth.

When I say "Lightweight APIs" in the paragraph above, I mean REST Web Services which generally use JSON. And what is JSON? JSON is a lightweight alternative to XML, which is increasingly used to bypass heavyweight XML parsing (and, in some cases, to bypass the security controls of the XMLHttpRequest object often used in AJAX).

JSON and REST can be seen as more efficient optimizations of what went before. OAuth is far from being "just another authentication mechanism". To understand OAuth involves understanding how it is used. For APIs, it generally involves an application (e.g. an Android app) accessing the API on the user's behalf. Phil Hunt has an excellent explanation of this aspect of OAuth here:
OAuth2 supports a range of new use case scenarios. Many do not directly involve a user or a browser, but rather define a client application acting on behalf of a resource owner's (e.g. the user) behalf using only HTTP to access REST based services in a lightweight fashion. From an authorization perspective, OAuth2 use cases introduce the new capability that client applications, each with their own identity, act on behalf of a users that own resources and can perform service calls with a specified "scope".
[ It's also worth following the link above to Phil Hunt's piece if you're ever wondered why the HTTP header "Authorization" is not called "Authentication"]

So, all in all, there are a lot of new technologies at play here: OAuth, JSON, APIs, and even REST. And there is also a new concept, the API Gateway. An API Gateway applies the security mechanisms such as OAuth, which is required to authenticate to an API. But, beyond this, it also provides:
- Monitoring of the API usage
- Alerting if the API is not responding correctly
- An audit trail of API access
- Validation of API content
- Redaction and tokenization of content being sent in API calls
- Mapping to identity stores

Putting it all together, here is a demo of how a user can authorize the Vordel API Gateway to access a JSON API with OAuth on their behalf.

In the video below, I'm using an Android tablet to authorize the Vordel API Gateway to access an API on my behalf. In the Android environment, I am already logged in with Google, and the API Gateway leverages this to ask me do I want to access the API using my Google logon. In this case the API is a Google URL-shortening API. When I authorize it, then from that point on the Vordel API Gateway is enabled to access this API on my behalf. At the API Gateway level, you can see in the video that the API usage and access is managed. The API Gateway administrator can add controls such as JSON validation, detection of private data leakage, and tokenization (replacement of private data with an opaque token). At no point does the user have to worry about creating OAuth headers - this is all taken care of at the API Gateway.

This is the first in a series of videos on the API Gateway topic - watch this space for more!


Tuesday, November 22, 2011

"A guy walks into a bar..."

I saw a good "A guy walks into a bar" joke retweeted via Roman Stanek's Twitter feed:

"An SEO guy walks into a bar, bars, pub, public house, Irish pub, drinks, beer, wine, liquor, grey goose, cristal"

I guess that is an old joke (though it was new to me: thanks Roman) but here's a new one: What would application security guy call an Irish bar? Not "O'Reilly's" or "O'Malley's" but "O' or 1=1--"

[ Explanation for non appsec folks: "O' or 1=1--" is an example of a SQL Injection attack which could be used against an API ]

Thursday, November 10, 2011

How to check for a HTTP 404 response code from a service

Here's a quick guide to checking for a HTTP 404 response code from a service, using the Vordel Gateway.

The first thing to note is that a "Connection" or a "Connect to URL" filter will return true if the back-end service returns a 404 code, because of the fact that the back-end service has successfully returned a response. You can then handle this 404 as you require. Often, it's a good idea to not return the full gory details of the 404 Not Found response to the client, and instead mask this information with a more friendly message. Or, you may wish to connect to a different URL instead. All of this involves branching on the value of the HTTP response code.

The simplest way to do this is to grab the latest version of the Vordel Gateway and check out the "Switch on Attribute Value" filter. This filter is great way to call a different policy shortcut based on the content of an attribute (in this case http.response.status).

Another way to do this is with a script. Below, I am using a script to check if the value of the http.response.status attribute is "404". If it is, I am branching to a "Set Message" filter which sets a nice friendly message to the client, telling them that the service is not available. Following that, I am using a "Reflect" filter to ensure that a 200 OK response code is returned to the client (not the 404 which came from the service).

Here is what the browser user sees. All of the information from the back-end service is replaced by the "Service not available" message.

This is pretty simple to handle at the Gateway, and it's interesting that, with relatively simple configuration like this, you can deploy the Gateway as Web traffic routing infrastructure.

Wednesday, November 9, 2011

How do I read an attribute from an LDAP directory, and place it into a SAML Assertion?

[ Update: Axway acquired Vordel in 2012 and the new name for the Vordel Gateway is the Axway API Gateway ]

Looking up user information from an LDAP directory is a common usage of the Vordel Gateway. Sometimes it's used for Message Enrichment in front of an applications server. This saves the applications server developer the hassle of looking up the attributes from the directory, since the attributes are handed to them on a plate, in the message, by the Gateway. So here is a quick tutorial on how to do this:

In the circuit you can see below, I am doing four things:

1) Authenticating the client against an LDAP directory (in this case Microsoft Active Directory) using WS-Security UsernameTokens.

2) Looking up attributes for the user (in this case, their telephone number)

3) "Injecting" a SAML 2.0 assertion into the message, including the SAML Attribute Statement

4) Passing the message back, with the SAML assertion now in it (so that we can see it). Here I could have used a "Connect to URL" filter to send the message to a URL, the "Messaging" filter to put it onto a queue, etc.

Let's look at each of these filters. Firstly, the filter which does WS-Security authentication against LDAP. This is shown below:

See that "Sample Active Directory Repository" under the "Repository Name" field above? That is a pointer to the connection I have configured to an LDAP directory. Actually, with the Vordel Gateway, you get a pre-configured sample LDAP connection which you can adapt to your own directory. This is what I did. The configuration for the LDAP connection can be found under "External Connections", as shown below:

You can see above that there are two things to configure: (a) The Authentication Repository Profile, and (b) The LDAP Connection itself. The LDAP Connection is how the Gateway binds to the LDAP server. The Authentication Repository Profile is how it finds the users which are being authenticated. So it is "bind then find". The Authentication Repository Profile (the "find") makes use of the LDAP connection (the "bind"). Note that if you only configure the LDAP connection, you won't see your LDAP authentication connection come up in the drop-down box on your authentication filters.

If I click on "Add/Edit", I can edit (and test) my LDAP connection. In the screenshot below, you can see that the test was successful, meaning I could connect from Policy Studio to the LDAP directory:

OK - so now let's look at the next filter in our circuit. This is a "Retrieve Attributes from Directory Server" filter, which you can find in the "Attributes" group in Policy Studio. I have configured it to retrieve the "telephoneNumber" filter from Active Directory:

If I look into Active Directory, I can see the phone number is in place for a sample user ("Joe Developer"). This is the phone number I am looking up:

Next, I am using an "Insert SAML Authentication Assertion" filter, and I have checked the box to place the SAML Attributes into it, as shown below:

So.... Now when I send a request to the Gateway on a path which is mapped to that policy (e.g. /MyAPI), I see that in the response I now have the SAML Assertion containing the user's phone number. Note that the WS-Security UsernameToken has been removed after use by the Vordel Gateway (you might have noticed the checkbox for this in the WS-Security configuration screenshot above).

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi=""
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
IssueInstant="2011-11-09T16:17:37Z" Version="2.0">
CN=Joe Developer,CN=Users,DC=Vordel,DC=com
Method="urn:oasis:names:tc:SAML:2.0:cm:sender-vouches" />
<saml:Conditions NotBefore="2011-11-09T16:17:36Z"
NotOnOrAfter="2011-11-09T16:22:36Z" />
<saml:AuthnStatement AuthnInstant="2011-11-09T16:17:37Z">
<saml:Attribute Name="telephoneNumber"
<Add xmlns="">

So that's it! That's all you need to do to authenticate a user against an LDAP directory, look up attributes, and insert attributes into an Attribute Statement in a SAML Assertion. You can find out more about the Vordel Gateway here, or email us at to get a copy.

Wednesday, November 2, 2011

Protecting API Keys for Cloud Services

My colleague Hugh Carroll has a good piece in Business Review Canada today about protecting API keys. Be sure to check it out. API keys are just as important to protect as other keys (e.g. SSL keys) but have not got nearly the same amount of awareness from security folks. How long before there is a major publicized API key breach?

Tuesday, November 1, 2011

How to configure load-balancing across services on the same host

There is a neat feature in the Vordel Gateway v6.2 which allows you to load-balance messages across endpoints that are on the same host. In the configuration of a Vordel Gateway, we have had the concept of a "Remote Host" for a long time. A Remote Host allows you to assign an address to map to one or more addresses. This allows you to perform load-balancing across back-end machines which the Vordel Gateway routes to.

You can see in the configuration below that I have setup a Remote Host using Policy Studio, and I have setup three addresses which differ only on the port they use. I am calling the Remote Host "LoadBalancedRequests". This is not a name of a real machine, but that doesn't matter (think of a hosts file). Now, when I route messages to this LoadBalancedRequests destination, the Gateway load-balances the requests across three addresses, which differ only based on port. You can see also that I have set the load-balancing algorithm to be "weighted by response time".

By the way, you might be thinking "why would someone have three different endpoints on the same machine to load-balance over?". One good reason is if they are running three different app server instances, to take efficient advantage of the available CPU and memory. This scenario is actually quite common. So now you know how to accomodate it on the Vordel Gateway :-)