Subscription policy

Within the subscription policy, you specify the name of the global-shared durable subscription that you want to set authorities for:

• In JMS, the DurableName property specifies the name of the global-shared durable subscription.
• In the Eclipse Amlen MQTT extension for supporting shared subscriptions, the SubName part of the MQTT shared subscription topic filter specifies the name of the global-shared durable subscription. The SUBSCRIBE request in MQTT specifies the following string:

  $SharedSubscription/SubName/topicFilter

  where:

  $SharedSubscription

  Indicates that the target of the SUBSCRIBE request is a global-shared subscription.

  SubName

  Is the name of the global-shared subscription; in this case, it is a global-shared durable subscription.

  This value must not include any forward slashes ( / ).

  topicFilter

  Is a standard MQTT topic filter for any type of topic subscription. It can contain a single topic name, or it can contain a topic filter that includes wildcards. This string corresponds to the Topic parameter that is specified in the topic policy that is associated with the subscription policy.

The subscription name (SubName) is specified in the subscription policy in the Subscription field. When you create a subscription policy, you authorize clients to use the global-shared durable subscription, but not the associated topic. Therefore, you must create a separate topic policy to authorize clients to use the associated topic. For more information about configuring topic policies to enable global-shared durable subscriptions to be used, see Topic filters for MQTT global-shared subscriptions.

When you create a subscription policy for a global-shared durable subscription, you can specify which messaging actions can be used by which of the clients that connect to the endpoints associated with the subscription policy. For a subscription policy, you can choose from a combination of the following actions:

• Control

  Allows clients to create and delete the global-shared durable subscription that is specified in the subscription policy.

  To create or delete a global-shared durable subscription, a client must also be allowed to receive messages. Therefore, if you select Control, you must also select Receive within the same subscription policy.

• Receive

  Allows clients to receive messages from the global-shared durable subscription that is specified in the subscription policy.

You can use filter attributes to restrict which clients can use the messaging actions that are specified in the subscription policy. You must specify at least one of the following filters:

• Client IP address

  Specifies the client IP addresses that are allowed to connect to Eclipse Amlen.

  The IP address can contain an asterisk (*), or a comma-separated list of IPv4 or IPv6 addresses or ranges. For example, 192.0.2.32, 192.0.0.0, 192.0.2.0-192.0.2.100. The range must be specified from low to high.

  IPv6 addresses must be enclosed in brackets [ ].

• User ID

  Specifies the messaging user ID that is allowed to connect to Eclipse Amlen by using the specified endpoint.

  You can use an asterisk (*) as the final character in the user ID as a wildcard to specify multiple user IDs.

• Group Name

  Specifies the messaging group that is allowed to connect to Eclipse Amlen by using the specified endpoint.

  You can use an asterisk (*) as the final character in the group name as a wildcard to specify multiple group names.

• Certificate Common Name

  Specifies the client certificate common name that must be used to connect to Eclipse Amlen by using the specified endpoint.

  You can use an asterisk (*) as the final character in the certificate common name as a wildcard to specify multiple certificate common names.

• Protocol

  Specifies which protocols are allowed to use the actions that are specified in the subscription policy on the global-shared durable subscription that is specified in the policy.

For example, for a subscription name exampleSub:

• One subscription policy specifies that only clients within a group that starts with example can control the shared subscription.
• Another subscription policy specifies that only clients that connect from the IP address range of 192.0.2.51-192.0.2.100 can receive messages from the shared subscription. The client must also have a user ID beginning with user.

The subscription policy configuration looks like the following examples:

curl -X POST  \
   -H 'Content-Type: application/json'  \
   -d  '{                          
           "SubscriptionPolicy": {   
               "exampleSubPolicy1": {
                "Description": "Subscription policy that restricts based on group membership.",
                "Subscription": "exampleSub*",
                "GroupID": "example",
                "ActionList": "Control,Receive"
              }
          }
      }
  '   \
http://127.0.0.1:9089/ima/v1/configuration/

curl -X POST  \
   -H 'Content-Type: application/json'  \
   -d  '{                          
           "SubscriptionPolicy": {   
               "exampleSubPolicy2": {
                "Description": "Subscription policy that restricts based on IP address and user ID.",
                "Subscription": "exampleSub*",
                "UserID": "user*",
                "ClientAddress": "192.0.2.51-192.0.2.100",
                "ActionList": "Receive"
              }
          }
      }
  '   \
http://127.0.0.1:9089/ima/v1/configuration/