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.