A complete guide on Azure Service Bus connection string

In this blog post, you will discover how to create and use the Azure Service Bus connection string and learn some of its common associated issues.

What is a connection string?

Generally, any connection string is a structured text string containing all the information needed for a client application to establish a connection to a specific service or resource, typically in a computer network.

It is widely used in various software systems to simplify the process of configuring connections without the need for complex configuration files or manual settings. Connection strings provide a convenient way to manage and configure connections to various services or resources, like databases, message queues, and more.

What exactly is an Azure Service Bus connection string?

In simple terms, a Service Bus connection string consists of key-value pairs separated by semicolons.

Azure Service Bus authorization methods

Azure Service Bus is a cloud-based messaging platform that enables communication between different components of distributed or different applications. It supports queuing and publishing/subscribing features, facilitating reliable and asynchronous communication. You can connect to Azure Service Bus by using a Shared Access Signatures (claims-based authorization) or Azure Active Directory (role-based authorization).

Azure AD allows more fine-grained per-user permissions. In an Azure Service Bus context, a Shared Access Signature is the traditional way that we can use to establish a secure and authenticated connection between your application and the Azure Service Bus messaging service.

Shared Access Signatures (SAS) are an authorization mechanism based on claims using simple tokens. With SAS, the actual keys are never transmitted over the network. Instead, keys are utilized to cryptographically sign data, which the service can later validate. SAS can be utilized in a manner similar to a username and password, where the client already possesses an authorization rule name and a corresponding key. It can be utilized much like a federated security model, where the client receives a time-limited and signed access token from a security token service without ever having access to the signing key.

Service Bus employs SAS authentication, which is set up through named Shared Access Authorization Policies (connection strings) that come with associated access rights and a pair of primary and secondary cryptographic keys. These keys are represented as 256-bit values in Base64. You have the option to define rules at the namespace level for both Service Bus queues and topics.

The Shared Access Policy consists of the following elements:

• Policy Name: identifies the SAS policy.
• Rights: represents the collection of granted Listen, Send, or Manage rights.
• Primary Key: a cryptographic key used to sign/validate SAS tokens.
• Secondary Key: a cryptographic key used to sign/validate SAS tokens.
• Primary Connection String and Secondary Connection String.

Azure Service Bus connection string parameters

The Azure Service Bus connection string contains the following pieces of information:

1. Endpoint: The URL that points to the Azure Service Bus instance you want to connect to.
2. Shared Access Key Name (SharedAccessKeyName): The name of the shared access key that provides security credentials for authentication.
3. Shared Access Key (SharedAccessKey): The actual security key associated with the shared access key name used to establish secure communication.
4. Entity Path (EntityPath): If you’re connecting to a specific queue or topic within the Service Bus, this specifies the path to that entity. This key-value is optional.

Here’s a typical example of how an Azure Service Bus connection string might be represented:

Endpoint=sb://your-servicebus-name.servicebus.windows.net/;SharedAccessKeyName=YourKeyName;SharedAccessKey=YourKey;EntityPath=YourQueueOrTopicName

This connection string would allow your application to securely connect to the specified Azure Service Bus instance and interact with the specified queue or topic.

How to create a connection string in Azure Service Bus?

To create a connection string for Azure Service Bus, you’ll need to follow these general steps:

• Create an Azure Service Bus Namespace
  • If you don’t have an Azure account, sign up for one.
  • Go to the Azure portal.
  • Create a new Azure Service Bus namespace. Provide a name for the namespace, choose a pricing tier, and configure other settings as needed.

• Optional: you can also create a Topic and/or a queue
  • Within your Service Bus namespace, navigate to the Entities > Topics or Entities > Queues section.
  • Create a new Topic or Queue.

•  Create or Manage Shared Access Policies – Once again, you can create a Shared Access Policy at the Service Bus namespace or at any entity level.
  • At the Service Bus namespace level.
    • Within your Service Bus namespace, navigate to the Settings > Shared access policies section.

• • • Create a new shared access policy or use an existing one by selecting the + Add option and providing a policy name (it needs to be unique at this level), and set up the correct rights: Listen, Send, or Manage.
      • Note: Selecting the Manage right will also automatically check the Send and the Listen.

• • At the Service Bus Entity level
    • Within your Service Bus namespace, navigate to the Entities > Topics or Entities > Queues section, and select a specific Queue or Topic

• • • Within your Entity, navigate to the Settings > Shared access policies section.
    • Create a new shared access policy or use an existing one by selecting the + Add option and providing a policy name (it needs to be unique at this level), and set up the correct rights: Listen, Send, or Manage.

• • The creation of this policy will automatically generate two keys (Primary Key and Secondary Key). Still, once you have a shared access policy, you can always regenerate a shared access key within that policy. This key will be used for authentication when creating the connection string.
• To access the Connection Strings
  • Access the policy you have just created or any existing policy, and from there, you can copy the Primary or Secondary Connection String.

Of course, these steps can also be created using Azure REST APIs or/and scripted using, for example, BICEP:

...
resource ruleListen 'authorizationRules@2022-01-01-preview' = {
   name: 'listenRule'
   dependsOn: [
      topicCreation
   ]
   properties: {
      rights: [
         'Listen'
      ]
   }
}
resource ruleSend 'authorizationRules@2022-01-01-preview' = {
   name: 'sendRule'
   dependsOn: [
      ruleListen
   ]
   properties: {
      rights: [
         'Send'
      ]
   }
}

How to use the Azure Service Bus connection?   

Now that we have our Connection String created, we can use it to connect different applications, tools, or Azure services like Logic Apps with our Service Bus. One tool that developers or administrators often use is the Service Bus Explorer, which was created by Paolo Salvatori. This tool grants users the capability to administer messaging entities efficiently, offering advanced features such as import/export functionality and the ability to perform testing on topics, queues, subscriptions, relay services, notification hubs, and events hubs.

Once you open the tool, the first thing we need to do is:

• To connect to a specific Service Bus. To do that, you need to select the option File > Connect.

• This will open a Connect to a Service Bus Namespace window, and one of the options to set up the connection is by using a Connection String. So on the Select a service bus namespace select the option Enter a connection string…</>

• On the Connection String panel, copy the Primary or Secondary Connection string that you can find on the policy we created earlier on the Azure Portal and then click OK.

• Depending on the right, this will give you access to perform a variety of actions.

Of course, as we mentioned before, this also can be used within Logic Apps to set up the Service Bus connector.

Common issues with connection strings in Azure Service Bus

Common issues with connection strings in Azure Service Bus can lead to connectivity problems or security vulnerabilities. Here are some of the common issues you might encounter:

• Incorrect Format: Connection strings must follow a specific format. Ensure you have the correct format with the necessary key-value pairs (Endpoint, SharedAccessKeyName, SharedAccessKey, and optionally EntityPath). Any typos or missing elements can prevent a successful connection.
• Missing or Incorrect Endpoint: The Endpoint should point to the correct Azure Service Bus namespace. If it’s incorrect or missing, your application won’t be able to connect.
• Invalid Shared Access Key: The SharedAccessKey is a sensitive credential. If you provide an incorrect key, your application won’t be authenticated, and the connection will fail.
• Expired or Revoked Key: If the shared access key has expired or has been revoked, your application won’t be able to establish a connection. Make sure you’re using a valid and current key.
• Incorrect Namespace or Resource Name: Mistyping the namespace or resource name in the connection string will prevent your application from connecting to the intended Service Bus instance.
• Incorrect Shared Access Policy: If you specify the wrong SharedAccessKeyName or if the policy does not have the required permissions (e.g., “Listen” or “Send”), your application won’t be authorized to perform the intended actions.
• Entity Path Mismatch: If you include the EntityPath key in the connection string, ensure it matches the queue or topic you’re trying to access. Using an incorrect or nonexistent entity path will result in connection failures.
• Security: For security concerns, storing connection strings in plain text within your application code or config files can expose sensitive information. Avoid hardcoding connection strings in source code and use secure configuration practices. For example, make sure you encrypt places like Azure Key Vault to store this information.

To avoid these common issues, it’s a good practice to centralize and manage your connection strings, use environment variables or Azure Key Vault for secure storage, and regularly review and update your connection strings as needed. If you encounter connection problems, carefully review the connection string and relevant configurations to identify and resolve the issue.

Conclusion 

• Using Azure Service Bus connection strings is a secure and easy way to establish a secure and authenticated connection between applications, tools, or services and the Azure Service Bus messaging platform. It is comprised of essential components such as the endpoint URL, shared access key name, shared access key, and the entity path (optionally).
• Careful attention to the correct format, proper credential management, and security measures are essential to ensure seamless and secure communication between applications, tools, or services and the Azure Service Bus.
• By understanding these essential aspects, you can facilitate reliable messaging and communication within distributed systems while adhering to the best data protection and connectivity practices.
• For Security concerns, storing connection strings in plain text within your application code or in config files can expose sensitive information. Make sure you encrypt places like Azure Key Vault to store this information.