Shared Access Signature Authentication with Service Bus
Updated: April 30, 2014
Shared Access Signature (SAS) authentication allows applications to authenticate to Microsoft Azure Service Bus using an access key configured on the namespace, or on the entity with which specific rights are associated. You can then use this key to generate a SAS token that clients can use to authenticate to Service Bus.
SAS authentication in Service Bus involves the configuration of a cryptographic key with associated rights on a Service Bus resource. Clients claim access to Service Bus resources by presenting a SAS token. This token consists of the resource URI being accessed, and an expiry signed with the configured key.
You can configure Shared Access Signature authorization rules on Service Bus queues, topics, and notification hubs. Support for Service Bus relays will be added in the near future.
SAS authentication uses the following elements:
SharedAccessAuthorizationRule: A 256-bit primary cryptographic key in Base64 representation, an optional secondary key, and a key name and associated rights (a collection of Listen, Send, or Manage rights).
SharedAccessSignature token: Generated using the HMAC-SHA256 of a resource string, consisting of the URI of the resource that is accessed and an expiry, with the cryptographic key. The signature and other elements described in the following sections are formatted into a string to form the SharedAccessSignature token.
Configuration for Shared Access Signature Authentication
You can configure the SharedAccessAuthorizationRule rule on Service Bus namespaces, queues, topics, or notification hubs. Configuring a SharedAccessAuthorizationRule on a Service Bus subscription is currently not supported, but you can use rules configured on a namespace or topic to secure access to subscriptions. For a working sample that illustrates this procedure, see the Using Shared Access Signature (SAS) authentication with Service Bus Subscriptions sample.
A maximum of 12 such rules can be configured on a Service Bus namespace, queue, topic, or notification hub. Rules that are configured on a Service Bus namespace apply to all entities in that namespace.
In this figure, the manageRuleNS, sendRuleNS, and listenRuleNS authorization rules apply to both queue Q1 and topic T1, while listenRuleQ and sendRuleQ apply to only queue Q1 and sendRuleT applies only to topic T1.
The key parameters of a SharedAccessAuthorizationRule are as follows:
A string that describes the authorization rule.
A base64-encoded 256-bit primary key for signing and validating the SAS token.
A base64-encoded 256-bit secondary key for signing and validating the SAS token.
A list of access rights granted by the authorization rule. These rights can be any collection of Listen, Send, and Manage rights.
When a Service Bus namespace is provisioned, a SharedAccessAuthorizationRule, with KeyName set to RootManageSharedAccessKey, is created by default. Two default SharedAccessAuthorizationRule objects are also configured for notification hubs: one with Listen, Send, and Manage rights, and another with only Listen rights.
Regenerating and Revoking keys for Shared Access Authorization Rules
It is recommended that you periodically regenerate the keys used in the SharedAccessAuthorizationRule. Applications should generally use the PrimaryKey to generate a SAS token. When regenerating the keys, you should replace the SecondaryKey with the old primary key, and generate a new key as the new primary key. This enables you to continue using tokens for authorization that were issued with the old primary key, and that have not yet expired.
If a key is compromised and you have to revoke the keys, you can regenerate both the PrimaryKey and the SecondaryKey of a SharedAccessAuthorizationRule, replacing them with new keys. This procedure invalidates all tokens signed with the old keys.
Generating a Shared Access Signature token
Any client that has access to the signing keys specified in the shared access authorization rule can generate the SAS token. It is formatted as follows:
The signature for the SAS token is computed using the HMAC-SHA256 of a string-to-sign with the PrimaryKey property of an authorization rule. The string-to-sign consists of a resource URI and an expiry, formatted as follows:
StringToSign = <resourceURI> + "\n" + expiry;
Note that you should use the encoded resource URI for this operation. The resource URI is the full URI of the Service Bus resource to which access is claimed. For example,
sb://<namespace>.servicebus.windows.net/<entityPath>; that is,
The expiry is represented as the number of seconds since the epoch 00:00:00 UTC on 1 January 1970.
The shared access authorization rule used for signing must be configured on the entity specified by this URI, or one of its hierarchical parents. For example,
http://contoso.servicebus.windows.net in the previous example.)
A SAS token is valid for all resources under the <resourceURI> used in the string-to-sign.
The KeyName in the SAS token refers to the keyName of the shared access authorization rule used to generate the token.
The URL-encoded-resourceURI must be the same as the URI used in the string-to-sign during the computation of the signature. It should be percent-encoded.
Using Shared Access Signature authentication
SAS authentication support is included in the Azure SDK version 2.0 and later. For more information, see How to use Shared Access Signature Authentication with Service Bus.