Variable substitution in messaging policies

You can use variable substitution in messaging policies to avoid configuring large numbers of messaging policies. You can set up a topic policy or queue policy so that the topic or queue parameter in the policy includes a user ID, group ID, client ID, or client certificate common name variable. The user ID, group ID, client ID, or common name is matched to the topic string or queue name, and access is granted to that topic tree or queue only.

The variables are:
  • ${UserID} for the user ID.
  • ${GroupID} for the group ID.
  • ${ClientID} for the client ID. You cannot use ${ClientID} in a subscription messaging policy.
  • ${CommonName} for the client certificate common name.

The topic parameter or queue parameter can contain multiple variables, but only one instance of each variable. For example, EXAMPLE/${ClientID}/A/${UserID} is valid, but EXAMPLE/${ClientID}/A/${ClientID} is not valid. You can specify extra characters along with the variable, for example EXAMPLE/${UserID}. However, if you use an unknown variable, the matching of the policy fails.

When you use variables, take care and be consistent with the position of the variable in your topic strings. For example, you have the following topic strings in your application:
  • MOBILEAPP/ACCOUNT/ClientID
  • MOBILEAPP/ACCOUNT/ClientID/PRIVILEGE
The first topic string is to authorize clients, and the second topic string is to authorize administrators. However, with these topic strings you can unintentionally allow access to the administrator topics. For example, if the topic policy has a topic of MOBILEAPP/ACCOUNT/${ClientID}, a malicious client can use a client ID that ends with /PRIVILEGE, and can gain access to the administrator topics.

Using the ${UserID} variable

The following example shows how you might configure a topic policy in a scenario where you have thousands of items that need tracking. You might also have thousands of users that want to subscribe to the status of one of these items. You can use the variable substitution option to avoid creating thousands of messaging policies. For example:
    Name:SubscribeItemTracking,
    Description:Topic policy for clients IDs with item tracking,
    Clientid:*,
    Topic:item/tracking/${UserID},
    ActionList:Subscribe

Using this topic policy, all clients can subscribe to topic string item/tracking/. However, each user can see only their items, as the ${UserID} is replaced by the user ID in the topic string. For example, there are two users, user_a and user_b. When user_a accesses the topic, they can subscribe only to the topic item/tracking/user_a. When user_b accesses the topic, they can subscribe only to the topic item/tracking/user_b. user_b cannot subscribe to the topic item/tracking/user_a.

Using the ${GroupID} variable

The following example shows how you might configure a topic policy in a scenario where you want to publish a message to all drivers who operate within a particular geographic region. You can use the variable substitution option to avoid creating thousands of messaging policies. For example:
    Name:PublishbyGeographicRegion,
    Description:Topic policy for group IDs by geographic region,
    Clientid:*,
    Topic:drivers/USA/${GroupID}/*,
    Action:Publish

Using this topic policy, a message can be published to topic string drivers/USA. Only users in a specific group can receive messages to which they are authorized, as the ${GroupID} is replaced by a specific group ID in the topic string. For example, there are two users, user_a and user_b. user_a is in the group Los Angeles. user_b is in the group San Francisco. user_a is authorized to receive only messages that are published to the topic drivers/USA/Los Angeles. user_b is authorized to receive only messages that are published to the topic drivers/USA/San Francisco. user_b cannot receive messages that are published to the topic drivers/USA/Los Angeles. user_c is in the group Los Angeles and the group San Francisco, so user_c is authorized to receive messages that are published to the topic drivers/USA/Los Angeles and the topic drivers/USA/San Francisco.

When you use the ${GroupID} variable but have different users with the same user ID in different groups with the same group ID, consider using unique group IDs. Unique group IDs help to ensure that only those users that you intend to have the authority to publish or subscribe to a topic can do so. For example, there are two users with the same user ID, Truck1. One user drives during the day and the other user drives during the night. They are both members of different groups which are both called Los Angeles; these groups called Los Angeles are nested as members of other groups. The driver who drives during the day has user ID Truck1 in group Los Angeles which is nested within group Daytime. The driver who drives during the night has user ID Truck1 in group Los Angeles which is nested within group Nighttime. If you specify the ${GroupID} variable, when it is replaced by the specific group ID in the topic string, both users receive messages that are published to the topic drivers/USA/Los Angeles. It might not be your intention for both of these users to receive these messages; you might only require one of these users to receive these messages and for the other user to receive messages from a different topic string. Consider using unique group names in this situation. You might consider replacing the group ID Los Angeles with group IDs similar to Los Angeles Day and Los Angeles Night.

A user can be a member of a maximum of 200 groups.