APM Cookbook: Dynamic APM Variables

Introduction

In this article we’ll discuss how to set a variable dynamically. The most common use case is setting something like a role attribute to use in SAML. 

We’ll use the example of setting a SAML attribute name “role” based on group membership. You need to set the value of “role” to either “managers”, “finance”, or “users”, depending on group membership. The trick is you can only send one value even if the user is a member of multiple groups. You have hierarchical preference first to “managers”, then “finance”, and everyone else gets the role “users”.

You could do this in an iRule or in a TCL expression in the Variable Assign object. However, I like to leverage the Visual Policy Editor GUI wherever possible so that I can quickly examine a policy flow and determine what’s happening without reading code, and most importantly, so that those who come after me don’t have to decipher what I was doing.

Macros Are Your Friend

We’ll assume you’ve already got a policy with a logon page, AD Auth, AD Query, and resource assignment for the SAML resource. We will create a macro named “Role Variable Setting” to perform this action after the AD Query. It goes after the AD Query because first we need to collect the group information. Here’s what the policy will look like with the piece we’re adding.

We want to create our flow in a macro because otherwise it could clutter up the policy itself, imagine twenty differetn conditions and all the branches you'd have. The macro can have all those branches exit to one place mkaing it all much cleaner and simpler to maintain. To create the macro you click “Add New Macro” inside the Visual Policy Editor (VPE).

You should use the “empty template” and name it something relevant to you, I’ve obviously named mine “Role Variable Setting”.  After building it out, here’s what my macro looks like when completed.

Setting the Conditions

We will start by building this section of the macro:

First I added an “empty” object from the general purpose tab. I named it “Empty (Group Check)”. Go to the branch rules tab and add rules as appropriate. Below is my complete macro. Notice the arrows on the right hand side of the branch rules list, you can reorder for preference with most preferred at the top. Remember how we said preference went to the managers role, then finance, and finally everyone else (fallback).

Your branch rules could be based on conditions like geolocation, landing URI, and many more. You can also go to the Advanced tab and modify the TCL expression to meet your needs if the simple GUI builder doesn’t meet them. The branch rule will be used if it resolves to “true”, and you can create complex logical statements with AND/OR even using the GUI. 

To build those branch rules I went into the Empty object and selected the Branch Rules tab. Then Add Branch Rule, selected the Simple tab, Add Expression, then AD Query, then User is a Member Of and entered the full DN path as you can see here, then Add Expression and Finished. This uses the data from our AD Query earlier in the policy flow.

Setting the Variable

Now we have three branches out of the Empty object and need to do something on them. We'll be building this section of the macro now:

On each branch I added a Variable Assign from the Assignment tab to set my custom variable. Here’s what it looks like inside the Variable Assign objects.

I got that by clicking Add New Entry and then inputting the values as you can see below.

Now that I have my macro complete all I need to do is add it from the Macros tab into the policy after the AD Query.

Using the Variable

Now to use that dynamically set variable I simply need to call %{session.custom.role} within APM, or if I need it in an iRule I can use [ACCESS::session data get session.custom.role], or if I need it in an TCL expression such as a branch rule I can use [mcget {session.custom.role}]. Here is an example where I’m using it as the value for a SAML attribute named “role”.

p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica} p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}