This sample demonstrates how to create and manage service identities in the Access Control Service for use with Service Bus and how to assign (and revoke) right from these service Identities so that they can send to or receive from a particular Service Bus entity or manage a particular branch of a Service Bus namespace.

The sample consists of a command-line tool and a reusable assembly that share the same code files. The command-line tool references the code files directly instead of using the assembly just to limit the number of files to be copied if the tool needs to be copied for management purposes.

SBAzTool

The tool, SBAzTool.exe, allows managing service identities and authorization rules associated with a Windows Azure Service Bus namespace.

The command structure is generally as follows:

sbaztool.exe [command] [command-arg] ... [command-arg] {option} {option}

Options are generally applicable across commands and supply information such as namespace names or access keys. The command "storeoptions" allows storing the options in the user context for subsequent command invocations. The commands "showoptions" and "clearoptions" allow showing and clearing the stored options.

The following options are defined:

-n <namespace> <namespace> is the Service Bus namespace to operate on. Required.
-k <key> <key> is the Access Control management key for the Access Control <namespace>-sb namespace. Required.
-q Suppresses the logo and all output except errors.

The following commands are defined:

makeid <name> [<key>] Creates a new service identity with <name> and a 32-byte, base64-encoded <key>. If <key> is not provided, it is generated and displayed.
showid <name> Gets details for the service identity with <name>
deleteid <name> Deletes the service identity with <name>
grant <op> <path> <name> Grants operation <op> on <path> for identity <name>. See remarks below.
revoke <op> <path> <name> Revokes permission for operation <op> on <path> for service identity <name>. See remarks below.
show <path> Shows all permissions effective for <path>
storeoptions Stores the options provided with the command in the user's context. Stored options are sticky across command line sessions and reboots until cleared.
showoptions Shows the stored options
clearoptions Clears the stored options.

The defined operations for the "grant" and "revoke" command are

Send Sending into a queue, topic or relay endpoint.
Listen Receiving from a queue or subscription or listening on the relay.
Manage Creating or deleting queues, topics, or subscriptions.

Details about the associated rights can be found in the product documentation. The <path> expression is a relative path on the Service Bus namespace, e.g. /myqueue or /my/endpoint. The leading slash is optional.

Prerequisites

If you haven't already done so, please read the release notes document that explains how to sign up for a Windows Azure account and how to configure your environment.

Example Usage

Here are a few examples for how to use the tool\

Managing service identities

sbaztool makeid johndoe -n mynamespace -k TiNj35FAIviW1ZxCcNUtEfowH//9jAYvU28Vz4NhRBM= Creates a new service identity 'johndoe' in namespace 'mynamespace' with the management key 'TiNj35FAIviW1ZxCcNUtEfowH//9jAYvU28Vz4NhRBM='. The actual namespace to use here is your own service namespace and the master management key for that namespace, which can be obtained from the management portal. The access key for the new service identity is generated and printed on the console. The -n and -k options can be omitted if they have been previously stored in the user context using the "storeoptions" command.
sbaztool makeid johndoe eYEysqKvEQUCGUf0BTXyBSJg0EUBs2Dh/zsJIkUqTIg= -n ... -k ... Creates a new service identity 'johndoe' with the preset key 'eYEysqKvEQUCGUf0BTXyBSJg0EUBs2Dh/zsJIkUqTIg=' in the desired namespace with the required key (see above).
sbaztool showid johndoe -n ... -k ... Shows the details (key) of the service identity 'johndoe'.
sbaztool deleteid johndoe -n ... -k ... Deletes the service identity 'johndoe'.

Managing access control rules

sbaztool grant Send / johndoe -n ... -k ... This operation grants 'Send' rights to the previously created service identity 'johndoe' on the namespace root. With that, 'johndoe' can send messages to any Service Bus entity within the namespace.
sbaztool grant Send /foo johndoe -n ... -k ... This operation grants 'Send' rights to the previously created service identity 'johndoe' on the namespace branch '/foo'. 'johndoe' can send messages to any Service Bus entity at and below the address '/foo'
sbaztool grant Listen /bar/baz johndoe -n ... -k ... This operation grants 'Listen' rights to the previously created service identity 'johndoe' on the namespace branch '/bar/baz'. 'johndoe' can receive messages from any Service Bus entity at and below the address '/bar/baz'
sbaztool revoke Listen /bar/baz johndoe -n ... -k ... This operation revokes the previously granted 'Listen' rights for service identity 'johndoe' on the namespace branch '/bar/baz'. 'johndoe' can no longer receive messages from Service Bus entities at and below the address '/bar/baz'.
sbaztool revoke Send /foo/zoo johndoe -n ... -k ... This operation revokes the previously granted 'Send' right for 'johndoe' from the namespace branch 'foo/zoo'. However, if the right was previously granted on a parent branch, like '/foo' as shown above, the operation will fail because inherited rights can not be revoked on parent branches.

Did you find this information useful? Please send your suggestions and comments about the documentation.