Monday, September 26, 2011

Authentication using custom tokens with the Vordel Gateway

Although standards like WS-Security exist, it's a fact of life that many organizations use custom authentication tokens to authenticate clients. This happens for a variety of reasons, such as the fact that WS-Security presupposes the usage of SOAP, and that just isn't an option for many people in the world of lightweight REST-based APIs.

Supporting custom authentication tokens is simple with the Vordel Gateway. It consists of two steps in Policy Studio:

1) Read in the username and password into two variables (called "attributes" in the Vordel Gateway).

If you want to read in a username from a HTTP header, for example, then drag in a "Retrieve from HTTP Header" filter, and type in the header name (e.g. "Username"), and then the attribute ID you want the value to be read into (e.g. "authentication.subject.id"). If you want the value to come from the Query-String (i.e. from the name-value pairs after the "?" in the URL), the check the box called "Use Query String Parameters".

If you want to read in a username from the message itself, use a "Retrieve from Message" filter, and then configure it with the XPath used to find the value. Tip: Save a copy of a message, then use the XPath Wizard (hit the little "magic wand" icon) to open it and tell the Gateway where your custom token is.

Then a similar procedure to read in the password from the message header (the "Retrieve from HTTP Header" filter) or message body (the "Retrieve from Message" filter). Usually I read this into the attribute "authentication.subject.password".

2) Drag in an "Attribute Authentication" filter (you can find this in the "Authentication" group) and chain it after the filters you setup before. In the example below, you can see that I've read the username and password into the attributes "authentication.subject.id" and "authentication.subject.password" respectively. I now ask the Gateway to validate these credentials.