Authorizing client messaging

You can use messaging policies to authorize client messaging. There are three types of messaging policies: Topic policies, queue policies, and subscription policies.

Topic policies can be used to authorize publishing or subscribing to a topic. Queue policies can be used to authorize sending, receiving, or browsing a queue. Subscription policies can be used to authorize the creation and deletion of global-shared durable subscriptions, or the authorization of a subscriber to receive messages from a global-shared durable subscription.

When you create a messaging policy, you specify a set of allowed actions for a particular topic string, queue, or subscription. The messaging policy specifies which clients can use those actions, based on criteria such as client ID, or IP address.

All messaging policies for an endpoint are checked for authorization in the order that they are specified on the endpoint. The policies are checked either until authorization is granted, or all messaging policies are checked. Therefore, you cannot create a messaging policy that restricts the authority of particular clients if another messaging policy grants more authority to those clients. For example, two topic policies are defined in the following order:
  • Topic: *
Action: Subscribe
MaxMessages: 10
  • Topic: A
Action: Subscribe
MaxMessages: 5
In this example, a subscription on topic B allows 10 messages to be buffered at a time. A subscription on topic A also allows 10 messages to be buffered at a time, as the more permissive messaging policy is defined first. To restrict the subscriptions on topic A to buffer only five messages, you must change the order of the policies.

A messaging policy can be applied to more than one endpoint. The messaging policies that are associated with the endpoint that a client is connected to are applied after the connection policies are applied.

Any changes to the following messaging policy parameters affect all subscriptions currently using the policy:
  • MaxMessages
  • MaxMessagesBehavior
  • DisconnectedClientNotification
  • MaxMessagesTimeToLive (for messages that are published or put after the change is made)

Wildcard based destinations

You can grant messaging authorization to a wildcard based topic, queue, or global-shared durable subscription by using an asterisk (*) in the Topic, Queue, or Subscription field.

The wildcard character matches 0 or more characters, including topic-level separators. Therefore, a single wildcard can match more than one level in a multi-level topic name. For example, A*E matches all the following topic names:
  • ARCHITECTURE
  • AN/APPLE
  • A/C/E
  • A/B/C/D/E
You must ensure that when you use wildcards in topic policies that the topic string has enough structure to limit the wildcard matching that occurs. For example, the following set of topic strings are used by an application:
  • DEVICE/clientID/LOCATION
  • DEVICE/clientID/FAULT
  • DEVICE/clientID/UPGRADE
The following topic strings are good choices for the Topic field of the topic policies:
  • DEVICE/${ClientID}/*
  • DEVICE/${ClientID}/LOCATION
  • DEVICE/${ClientID}/FAULT
  • DEVICE/${ClientID}/UPGRADE
The following topic strings are too broad in scope to give enough control and partition the resources that are accessible by each client:
  • DEVICE/*
  • */${ClientID}/*
In this example, the following topic string is used by an application to send notifications to mobile devices, where each user can have multiple devices:
  • NOTIFY/UserID/ClientID/NOTIFICATION
The devices that receive the notification can be authorized by using a topic policy with a destination such as the following topic string:
  • NOTIFY/${UserID}/${ClientID}/NOTIFICATION
The application that sends the notification can have a wider authorization, such as the following topic string:
  • NOTIFY/*/*/NOTIFICATION