Authenticate an application with Azure Active Directory to access Event Hubs resources
Microsoft Azure provides integrated access control management for resources and applications based on Azure Active Directory (Azure AD). A key advantage of using Azure AD with Azure Event Hubs is that you don't need to store your credentials in the code anymore. Instead, you can request an OAuth 2.0 access token from the Microsoft Identity platform. The resource name to request a token is
https://eventhubs.azure.net/, and it's the same for all clouds/tenants (For Kafka clients, the resource to request a token is
https://<namespace>.servicebus.windows.net). Azure AD authenticates the security principal (a user, group, or service principal) running the application. If the authentication succeeds, Azure AD returns an access token to the application, and the application can then use the access token to authorize request to Azure Event Hubs resources.
When a role is assigned to an Azure AD security principal, Azure grants access to those resources for that security principal. Access can be scoped to the level of subscription, the resource group, the Event Hubs namespace, or any resource under it. An Azure AD security can assign roles to a user, a group, an application service principal, or a managed identity for Azure resources.
A role definition is a collection of permissions. Azure role-based access control (Azure RBAC) controls how these permissions are enforced through role assignment. A role assignment consists of three elements: security principal, role definition, and scope. For more information, see Understanding the different roles.
Built-in roles for Azure Event Hubs
Azure provides the following Azure built-in roles for authorizing access to Event Hubs data using Azure AD and OAuth:
- Azure Event Hubs Data Owner: Use this role to give complete access to Event Hubs resources.
- Azure Event Hubs Data Sender: Use this role to give send access to Event Hubs resources.
- Azure Event Hubs Data Receiver: Use this role to give receiving access to Event Hubs resources.
For Schema Registry built-in roles, see Schema Registry roles.
Our preview release supported adding Event Hubs data access privileges to Owner or Contributor role. However, data access privileges for Owner and Contributor role are no longer honored. If you are using the Owner or Contributor role, switch to using the Azure Event Hubs Data Owner role.
Authenticate from an application
A key advantage of using Azure AD with Event Hubs is that your credentials no longer need to be stored in your code. Instead, you can request an OAuth 2.0 access token from Microsoft identity platform. Azure AD authenticates the security principal (a user, a group, or service principal) running the application. If authentication succeeds, Azure AD returns the access token to the application, and the application can then use the access token to authorize requests to Azure Event Hubs.
Following sections shows you how to configure your native application or web application for authentication with Microsoft identity platform 2.0. For more information about Microsoft identity platform 2.0, see Microsoft identity platform (v2.0) overview.
For an overview of the OAuth 2.0 code grant flow, see Authorize access to Azure Active Directory web applications using the OAuth 2.0 code grant flow.
Register your application with an Azure AD tenant
The first step in using Azure AD to authorize Event Hubs resources is registering your client application with an Azure AD tenant from the Azure portal. When you register your client application, you supply information about the application to AD. Azure AD then provides a client ID (also called an application ID) that you can use to associate your application with Azure AD runtime. To learn more about the client ID, see Application and service principal objects in Azure Active Directory.
The following images show steps for registering a web application:
If you register your application as a native application, you can specify any valid URI for the Redirect URI. For native applications, this value does not have to be a real URL. For web applications, the redirect URI must be a valid URI, because it specifies the URL to which tokens are provided.
After you've registered your application, you'll see the Application (client) ID under Settings:
For more information about registering an application with Azure AD, see Integrating applications with Azure Active Directory.
Create a client secret
The application needs a client secret to prove its identity when requesting a token. To add the client secret, follow these steps.
Navigate to your app registration in the Azure portal.
Select the Certificates & secrets setting.
Under Client secrets, select New client secret to create a new secret.
Provide a description for the secret, and choose the wanted expiration interval.
Immediately copy the value of the new secret to a secure location. The fill value is displayed to you only once.
Assign Azure roles using the Azure portal
After you register the application, you assign the application's service principal to an Event Hubs Azure AD role described in the Build-in roles for Azure Event Hubs section.
In the Azure portal, navigate to your Event Hubs namespace.
On the Overview page, select the event hub for which you want to assign a role.
Select Access Control (IAM) to display access control settings for the event hub.
Select the Role assignments tab to see the list of role assignments. Select the Add button on the toolbar and then select Add role assignment.
On the Add role assignment page, do the following steps:
Select the Event Hubs role that you want to assign.
Search to locate the security principal (user, group, service principal) to which you want to assign the role. Select the registered application from the list.
Select Save to save the role assignment.
Switch to the Role assignments tab and confirm the role assignment. For example, the following image shows that mywebapp is in the Azure Event Hubs Data Sender role.
You can follow similar steps to assign a role scoped to Event Hubs namespace, resource group, or subscription. Once you define the role and its scope, you can test this behavior with samples in this GitHub location. To learn more on managing access to Azure resources using Azure RBAC and the Azure portal, see this article.
Client libraries for token acquisition
Once you've registered your application and granted it permissions to send/receive data in Azure Event Hubs, you can add code to your application to authenticate a security principal and acquire OAuth 2.0 token. To authenticate and acquire the token, you can use either one of the Microsoft identity platform authentication libraries or another open-source library that supports OpenID or Connect 1.0. Your application can then use the access token to authorize a request against Azure Event Hubs.
These samples use the old Microsoft.Azure.EventHubs library, but you can easily update it to using the latest Azure.Messaging.EventHubs library. To move the sample from using the old library to new one, see the Guide to migrate from Microsoft.Azure.EventHubs to Azure.Messaging.EventHubs.
This sample has been updated to use the latest Azure.Messaging.EventHubs library.
- To learn more about Azure RBAC, see What is Azure role-based access control (Azure RBAC)?
- To learn how to assign and manage Azure role assignments with Azure PowerShell, Azure CLI, or the REST API, see these articles:
See the following related articles:
- Authenticate a managed identity with Azure Active Directory to access Event Hubs Resources
- Authenticate requests to Azure Event Hubs using Shared Access Signatures
- Authorize access to Event Hubs resources using Azure Active Directory
- Authorize access to Event Hubs resources using Shared Access Signatures