Authentication and authorization with Azure Active Directory (Preview)

This article describes how to authenticate Azure Event Grid publishing clients using Azure Active Directory (Azure AD).

Overview

The Microsoft Identity platform provides an integrated authentication and access control management for resources and applications that use Azure Active Directory (Azure AD) as their identity provider. Use the Microsoft Identity platform to provide authentication and authorization support in your applications. It's based on open standards such as OAuth 2.0 and OpenID Connect and offers tools and open-source libraries that support many authentication scenarios. It provides advanced features such as Conditional Access that allows you to set policies that require multifactor authentication or allow access from specific locations, for example.

An advantage that improves your security stance when using Azure AD is that you don't need to store credentials, such as authentication keys, in the code or repositories. Instead, you rely on the acquisition of OAuth 2.0 access tokens from the Microsoft Identity platform that your application presents when authenticating to a protected resource. You can register your event publishing application with Azure AD and obtain a service principal associated with your app that you manage and use. Instead, you can use Managed Identities, either system assigned or user assigned, for an even simpler identity management model as some aspects of the identity lifecycle are managed for you.

Role-based access control (RBAC) allows you to configure authorization in a way that certain security principals (identities for users, groups, or apps) have specific permissions to execute operations over Azure resources. This way, the security principal used by a client application that sends events to Event Grid must have the RBAC role EventGrid Data Sender associated with it.

Security principals

There are two broad categories of security principals that are applicable when discussing authentication of an Event Grid publishing client:

  • Managed identities. A managed identity can be system assigned, which you enable on an Azure resource and is associated to only that resource, or user assigned, which you explicitly create and name. User assigned managed identities can be associated to more than one resource.
  • Application security principal. It's a type of security principal that represents an application, which accesses resources protected by Azure AD.

Regardless of the security principal used, a managed identity or an application security principal, your client uses that identity to authenticate before Azure AD and obtain an OAuth 2.0 access token that's sent with requests when sending events to Event Grid. That token is cryptographically signed and once Event Grid receives it, the token is validated. For example, the audience (the intended recipient of the token) is confirmed to be Event Grid (https://eventgrid.azure.net), among other things. The token contains information about the client identity. Event Grid takes that identity and validates that the client has the role EventGrid Data Sender assigned to it. More precisely, Event Grid validates that the identity has the Microsoft.EventGrid/events/send/action permission in an RBAC role associated to the identity before allowing the event publishing request to complete.

If you're using the Event Grid SDK, you don't need to worry about the details on how to implement the acquisition of access tokens and how to include it with every request to Event Grid because the Event Grid data plane SDKs do that for you.

Client configuration steps to use Azure AD authentication

Perform the following steps to configure your client to use Azure AD authentication when sending events to a topic, domain, or partner namespace.

  1. Create or use a security principal you want to use to authenticate. You can use a managed identity or an application security principal.
  2. Grant permission to a security principal to publish events by assigning the EventGrid Data Sender role to the security principal.
  3. Use the Event Grid SDK to publish events to an Event Grid.

Authenticate using a managed identity

Managed identities are identities associated with Azure resources. Managed identities provide an identity that applications use when using Azure resources that support Azure AD authentication. Applications may use the managed identity of the hosting resource like a virtual machine or Azure App service to obtain Azure AD tokens that are presented with the request when publishing events to Event Grid. When the application connects, Event Grid binds the managed entity's context to the client. Once it's associated with a managed identity, your Event Grid publishing client can do all authorized operations. Authorization is granted by associating a managed entity to an Event Grid RBAC role.

Managed identity provides Azure services with an automatically managed identity in Azure AD. Contrasting to other authentication methods, you don't need to store and protect access keys or Shared Access Signatures (SAS) in your application code or configuration, either for the identity itself or for the resources you need to access.

To authenticate your event publishing client using managed identities, first decide on the hosting Azure service for your client application and then enable system assigned or user assigned managed identities on that Azure service instance. For example, you can enable managed identities on a VM, an Azure App Service or Azure Functions.

Once you have a managed identity configured in a hosting service, assign the permission to publish events to that identity.

Authenticate using a security principal of a client application

Besides managed identities, another identity option is to create a security principal for your client application. To that end, you need to register your application with Azure AD. Registering your application is a gesture through which you delegate identity and access management control to Azure AD. Follow the steps in section Register an application and in section Add a client secret. Make sure to review the prerequisites before starting.

Once you have an application security principal and followed above steps, assign the permission to publish events to that identity.

Note

When you register an application in the portal, an application object and a service principal are created automatically in your home tenant. Alternatively, you can use Microsot Graph to register your application. However, if you register or create an application using the Microsoft Graph APIs, creating the service principal object is a separate step.

Assign permission to a security principal to publish events

The identity used to publish events to Event Grid must have the permission Microsoft.EventGrid/events/send/action that allows it to send events to Event Grid. That permission is included in the built-in RBAC role EventGrid Data Sender. This role can be assigned to a security principal, for a given scope, which can be a management group, an Azure subscription, a resource group, or a specific event grid topic, domain, or partner namespace. Follow the steps in Assign Azure roles to assign a security principal the EventGrid Data Sender role and in that way grant an application using that security principal access to send events. Alternatively, you can define a custom role that includes the Microsoft.EventGrid/events/send/action permission and assign that custom role to your security principal.

With RBAC privileges taken care of, you can now build your client application to send events to Event Grid.

Note

Event Grid supports more RBAC roles for purposes beyond sending events. For more information, seeEvent Grid built-in roles.

Publish events using Event Grid's client SDKs

Use Event Grid's data plane SDK to publish events to Event Grid. Event Grid's SDK support all authentication methods, including Azure AD authentication.

Prerequisites

Following are the prerequisites to authenticate to Event Grid.

Publish events using Azure AD Authentication

To send events to a topic, domain or partner namespace, you can build the client in the following way. The api version that first provided support for Azure AD authentication is 2021-06-01-preview. Use that API version or a more recent version in your application.

        DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
        EventGridPublisherClient cloudEventClient = new EventGridPublisherClientBuilder()
                .endpoint("<your-event-grid-topic-domain-or-partner-namespace-endpoint>?api-version=2021-06-01-preview")
                .credential(credential)
                .buildCloudEventPublisherClient();

If you're using a security principal associated with a client publishing application, you have to configure environmental variables as shown in the Java SDK readme article. The DefaultCredentialBuilder reads those environment variables to use the right identity. For more information, see Java API overview.

For more information, see the following articles:

Disable key and shared access signature authentication

Azure AD authentication provides a superior authentication support than that's offered by access key or Shared Access Signature (SAS) token authentication. With Azure AD authentication, the identity is validated against Azure AD identity provider. As a developer, you won't have to handle keys in your code if you use Azure AD authentication. you'll also benefit from all security features built into the Microsoft Identity platform, such as Conditional Access, that can help you improve your application's security stance.

Once you decide to use Azure AD authentication, you can disable authentication based on access keys or SAS tokens.

Note

Acess keys or SAS token authentication is a form of local authentication. you'll hear sometimes referring to "local auth" when discussing this category of authentication mechanisms that don't rely on Azure AD. The API parameter used to disable local authentication is called, appropriately so, disableLocalAuth.

The following CLI command shows the way to create a custom topic with local authentication disabled. The disable local auth feature is currently available as a preview and you need to use API version 2021-06-01-preview.

az resource create --subscription <subscriptionId> --resource-group <resourceGroup> --resource-type Microsoft.EventGrid/topics --api-version 2021-06-01-preview --name <topicName> --location <location> --properties "{ \"disableLocalAuth\": true}"

For your reference, the following are the resource type values that you can use according to the topic you're creating or updating.

Topic type Resource type
Domains Microsoft.EventGrid/domains
Partner Namespace Microsoft.EventGrid/partnerNamespaces
Custom Topic Microsoft.EventGrid/topics

If you're using PowerShell, use the following cmdlets to create a custom topic with local authentication disabled.


Set-AzContext -SubscriptionId <SubscriptionId>

New-AzResource -ResourceGroupName <ResourceGroupName> -ResourceType Microsoft.EventGrid/topics -ApiVersion 2021-06-01-preview -ResourceName <TopicName> -Location <Location> -Properties @{disableLocalAuth=$true}

Note

Resources