Securing Connection Strings To Namespaces

This page refers to the legacy Azure Service Bus transport that uses the WindowsAzure.ServiceBus NuGet package. This package is currently on extended support until May 2022, after which it will be out of support according to the support policy. All users should migrate to the Azure Service Bus transport transport.

Namespace Aliases

Versions 6 and below allow the routing of messages across different namespaces by adding connection string information behind the @ sign in any address notation. As address information is included in messages headers, the headers include both the queue name as well as the connection string. For instance, the ReplyTo header value has of the following structure:

[queue name]@Endpoint=sb://[namespace name];SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=[key]

This carries a risk of exposing sensitive connection strings with unwanted 3rd parties, for example when messages are exchanged with untrusted parties (native outgoing integration, messages export, etc) or when body content is added to log files which are then shared.

To reduce this risk, Versions 7 and above can map an alias to a namespace connection string. For backwards compatibility this new behavior is disabled by default. To enable namespace aliases use the UseNamespaceNamesInsteadOfConnectionStrings() configuration API setting.

var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();

When this setting is enabled, the ReplyTo header will no longer contain the full connection string and will be structured as following:

[queue name]@[alias]
Using namespace aliases is currently NOT compatible with ServiceControl. A ServiceControl transport adapter is required in order to leverage both.


To perform cross-namespace routing, a connection string has to be mapped to a corresponding alias. For example:

var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
var routing = transport.NamespaceRouting();
    name: "destination1",
    connectionString: "Endpoint=sb://;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]");
    name: "destination2",
    connectionString: "Endpoint=sb://;SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]");
All endpoints in a system need to be configured with the same namespace aliases and connection string information.

For a detailed explanation on configuring namespace mappings for namespace routing and partitioning, see Multiple Namespaces Support.

Backward compatibility

All endpoints need to be upgraded to Version 7 prior to enabling this feature. Older versions of the transport cannot use namespace names.

Internally the transport (Versions 7 and above) uses namespace alias to refer to namespaces. Even when using the ConnectionString(string connectionString) method on the configuration API directly, as shown below, it will cause the transport to add a mapping between a namespace alias default and the provided connection string internally.

var transport = endpointConfiguration.UseTransport<AzureServiceBusTransport>();
    connectionString: "Endpoint=sb://[NAMESPACE];SharedAccessKeyName=[KEYNAME];SharedAccessKey=[KEY]");

Without enabling the UseNamespaceAliasInsteadOfConnectionStrings() behavior, the transport will ensure that all outbound headers are converted to the queueName@connectionString format before delivering messages. This ensures backward compatibility among endpoints of different versions.

By calling UseNamespaceAliasNameInsteadOfConnectionString() the transport will change its behavior. Instead of embedding connection strings in headers, namespace aliases will be used instead.

Any incoming message can have headers in either format, the transport will automatically convert connection strings on the wire to namespace alias for internal use.

Related Articles

Last modified