Hello Joe

Hopefully you’ve been able to set up your new and shiny gateway and go through the simple hello world policy. In this post we are going to extend the HelloWorld policy to introduce some authentication and gateway attributes.


So far we have used the set message filter to set the message value to some arbitrary text, and then used the reflect filter to bounce this back to the requestor with an http response code of 200.

To add some simple authentication, the first thing we will need is a User.

1. Creating the user

Select the users section on the configuration navigation panel on the left hand side.

image image

Then click on the Users node of the User Store


Click Add – and enter some details for your user (I have used ‘joe’ with a password of ‘joe’)


Note the option to assign an X509 cert here – this can be used for crypto operations and mutual SSL – which are topics for a later post.

Notice also the attributes tab, click this and add an attribute


I’m going to set an age attribute with a value of 30


Add a couple more if you feel like experimenting – just the one will serve for the purpose of this post – remember – pretty much everything is CASE SENSITIVE by default.

Click OK and now you have your user “joe” in the built in user store


2. Adding authentication to the policy

Now we have a user to work with, lets put some authentication requirements on our Hello World policy – starting with http basic. Navigate to the Hello world policy (select the policies section on the left hand navigation panel and click on the policy in the tree node, or if it is already there select it from the list of tabs in the design panel (central panel by default).

Type “authentication” into the filter text box at the top of the pallet – you should be getting used to where things are by now… and expand the Authentication category.


In the authentication category you will see many options for providing authentication to services – some of which enable out of the box integration with third party IdM products –  we won’t be looking at these in the blog but feel free to submit a comment if you need assistance with something specific like Tivoli, RSA, CA, ADFS etc…

Remember that each of the filters here will have a context based dialogue that allows you to enter the parameters required to integrate – NO CODE REQUIRED.

For those of you not familiar with how  Mutual SSL authentication (or Client certificate authentication) don’t expect to be able to use this just yet, as we haven’t set up an https interface … so it’s not possible just yet …. have patience

Anyone wanting to play with kerberos – feel free but I’m not a big fan so won’t be covering it here unless someone forces me too Smile

Left click, hold and drag the image filter onto the design canvas – it is best to drop it on to an “empty” part of the canvas – dropping filters on top of each other or directly on to connectors has a different effect which we will cover later.

Configure the filter with the following settings:


and click Finish – you should have something like this.


Remember any filter that is not the start filter, and is not connected to it by a downstream path is not part of the policy.

Obviously it makes sense here for http basic authentication to be the first step we perform in the policy – it may seem trivial right now, but we don’t want to waste processing power performing tasks for an un-authenticated user!

There are a couple of ways of achieving this, and it’s basically down to personal preference – either set the image filter as the start filter (right click – set as start) and then join the others, or use the image to link the http basic filter to the set message filter… then set it as start – I typically do the later.

image   image


There are no RED warnings – so all attribute requirements are satisfied – all that remains to be done is deploy the update policy to the gateway

to deploy the configuration hit the F6 function key, or click the image deploy icon – changes to policy do not affect the running [active] gateway until they are deployed.

In a browser of your choice – load up your hello world uri


– you should be challenged for a user name and password


Enter the credentials for the user you added in the first step of this tutorial – in my case – ‘joe’ and ‘joe’

and you should be granted access to the hello world page


** There are a couple of things to keep in mind when it comes to using browsers as a test client; they tend to cache authorisation headers – so if you got your username and password wrong here then to try again you may have to shut down ALL browser sessions before you can try again – or even clear your browsing history – ultimately it is better to use a testing tool like Vordel SOAP Box that will all0w you to send a variety of requests at the gateway (including http GETs) without the browser functionality getting in the way of you testing – we’ll take a look at SOAP Box in the next couple of blogs – and its a free download with no “pro-version” limitations **

So we have layered  http basic authentication over the hello world service – now that we have a user identity established as part of the policy we can add some personalisation – let’s start by changing the welcome message.

Go back to the hello world policy and double click on the set message filter –

edit the text to say Hello $

Notice that as soon as you press the ‘$’ key a scrollable list of attributes is presented for auto insertion – continue to type “authentication” and then select the “authentication.subject.id” attribute and hit enter. Your message text should now look like this.

Hello ${authentication.subject.id}

Click finish.

This is the general syntax for attribute insertion (or substitution) – the authentication.subject.id attribute is populated by way of the http basic authentication filter we inserted earlier. You can see what attributes are generated, required and consumed by right clicking on the design canvas and selecting the “show all attributes” menu item.


There are other attributes available (populated by default as part of handling an http request – http.request.uri and http.client.addr for example that are not shown in this list – all the attributes are documented in detail in the gateway documentation. available at http://localhost:8090/docs/

Deploy [F6 function key, or click the image deploy] your updated policy and browse to the url http://localhost:8080/blog/tutorial01/helloworld


for fun you could then try setting your message to something like this.

Hello ${authentication.subject.id}
You are on ip address ${http.request.clientaddr}
and accessing the relative path ${http.request.uri}
via the HTTP method: ${http.request.verb}

Next we will look at retrieving joe’s age from the user store.

In the filter textbox on the pallet – type attributes and expand the attributes section


Again there is a wealth of functionality that deals with attributes of all kinds, shapes and sizes – scrolling down you will find the filter we need for this example


Remember you can customise the filters that are shown or hidden, and add your most frequently used filters to the Favourites (Favorites for you folks in the US) category.

If you fancy a change and don’t want to drag and drop then you could right click on the canvas and select add filter, then select the retrieve from user store filter.



Configure the filter to use the authentication.subject.id as the User ID, – the authentication.subject.id will be used to uniquely identify the user whose attributes we wish to retrieve. – you can add individual attributes to selectively retrieve, or leave the attribute list empty to return ALL attributes for the user from the built in store



Now wire in the retrieve from user store filter. Logically it would not make sense to retrieve attributes before we have identified the user – so you should be able to figure out where this one should go – again there are different ways to rewire the policy – by preference I connect the filter I have just added using the success connector image to the filter that should follow it, then move the end of the path that should connect above it like this.


Connect the retrieve from user store filter to the set message filter


click the success path joining the http basic filter and the set message filter then drag the arrow end to the retrieve from user store filter

image             image

click the arrow head and drag it onto the retrieve from user store filter and release



Now we have a nice visual representation of the flow –
1. authenticate
2. get attributes from user store
3. set the personalised message
4. return the message to the requestor

we just need to update the message to include our ‘age’ attribute

change the message text in the set message filter to

Hello ${authentication.subject.id} you are ${user.age} years old

Notice that the age attribute is prefixed with “user.” this is because the attribute belongs to the user, and NOT the message – distinguishing between user attributes and message attributes becomes more important later when inserting SAML assertions amongst other things.

Deploy the updated policy and check it out….


You can change “joe’s age” by modifying the age attribute value for joe in the user store – remember to re-deploy before you test again.


Notice that the Set Message filter is now RED – warning that one or more required attributes may not be available at run-time – this is because we used the retrieve filter to return ALL the values – therefore the GUI cannot confirm with any certainty that the “age” attribute will ALWAYS be available. If you show all attributes you will see it is the user.age attribute that is the cause for concern.

What you should have learnt

  • How to add a user (with attributes) to the local user repository
  • How to configure http basic authentication against the local user repository
  • How to insert a filter (rather than just add) into an existing circuit
  • How to retrieve user attributes from the local user repository
  • How to substitute retrieved attributes using the wildcard syntax into the set message filter
  • Where to access the list of available attributes (in the product docs!!)
  • How to detect attribute dependencies in policies
  • How to navigate between the different configuration sections – policies, services, users


  • User attributes are prefixed with “user.”
  • selecting a success or failure “arrow” allows the arrow head to be dragged and reconnected to change the flow of the policy
  • ALL changes need to be deployed – even updating user attributes
  • Changing the starting filter affects the whole policy – there is more than one way to achieve the desired flow through the policy / filter circuit

Up next….

Fault handling and policy shortcuts… a short introduction on how to create re-usable policies that can be invoked from multiple “parent” policies, and how this helps to keep a clean and clear visual representation of gateway policies; and how to create policies that handle errors and failures.

This entry was posted in How To, Vordel, XML Gateway and tagged , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s