Authenticate and authorize an application with Microsoft Entra ID to access Azure Relay entities

Azure Relay supports using Microsoft Entra ID to authorize requests to Azure Relay entities (Hybrid Connections, WCF Relays). With Microsoft Entra ID, you can use Azure role-based access control (Azure RBAC) to grant permissions to a security principal, which may be a user, group, or application service principal. To learn more about roles and role assignments, see Understanding the different roles.

Note

This feature is generally available in all regions except Microsoft Azure operated by 21Vianet.

Overview

When a security principal (a user, group, application) attempts to access a Relay entity, the request must be authorized. With Microsoft Entra ID, access to a resource is a two-step process.

1. First, the security principal’s identity is authenticated, and an OAuth 2.0 token is returned. The resource name to request a token is https://relay.azure.net. If an application is running within an Azure entity such as an Azure VM, a virtual machine scale set, or an Azure Function app, it can use a managed identity to access the resources.
2. Next, the token is passed as part of a request to the Relay service to authorize access to the specified resource (hybrid connections, WCF relays). Microsoft Entra authorizes access rights to secured resources through Azure role-based access control (Azure RBAC). Azure Relay defines a set of Azure built-in roles that encompass common sets of permissions used to access Relay entities. You can also define custom roles for accessing the data. For a list of built-in roles supported by Azure Relay, see Azure Built-in roles for Azure Relay. Native applications and web applications that make requests to Relay can also authorize with Microsoft Entra ID.

Azure built-in roles for Azure Relay

For Azure Relay, the management of namespaces and all related resources through the Azure portal and the Azure resource management API is already protected using the Azure RBAC model. Azure provides the below Azure built-in roles for authorizing access to a Relay namespace:

Role	Description
Azure Relay Owner	Use this role to grant full access to Azure Relay resources.
Azure Relay Listener	Use this role to grant listen and entity read access to Azure Relay resources.
Azure Relay Sender	Use this role to grant send and entity read access to Azure Relay resources.

Resource scope

Before you assign an Azure role to a security principal, determine the scope of access that the security principal should have. Best practices dictate that it's always best to grant only the narrowest possible scope.

The following list describes the levels at which you can scope access to Azure Relay resources, starting with the narrowest scope:

• Relay entities: Role assignment applies to a specific Relay entity like a hybrid connection or a WCF relay.
• Relay namespace: Role assignment applies to all the Relay entities under the namespace.
• Resource group: Role assignment applies to all the Relay resources under the resource group.
• Subscription: Role assignment applies to all the Relay resources in all of the resource groups in the subscription.

Note

Keep in mind that Azure role assignments may take up to five minutes to propagate. For more information about how built-in roles are defined, see Understand role definitions. For information about creating Azure custom roles, see Azure custom roles.

Authenticate from an app

A key advantage of using Microsoft Entra ID with Azure Relay 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. Microsoft Entra authenticates the security principal (a user, a group, or service principal) running the application. If authentication succeeds, Microsoft Entra ID returns the access token to the application, and the application can then use the access token to authorize requests to Azure Relay.

Following sections shows you how to configure your console application for authentication with Microsoft identity platform 2.0. For more information, see Microsoft identity platform (v2.0) overview.

For an overview of the OAuth 2.0 code grant flow, see Authorize access to Microsoft Entra web applications using the OAuth 2.0 code grant flow.

Register your application with a Microsoft Entra tenant

The first step in using Microsoft Entra ID to authorize Azure Relay entities is registering your client application with a Microsoft Entra tenant from the Azure portal. When you register your client application, you supply information about the application to AD. Microsoft Entra ID then provides a client ID (also called an application ID) that you can use to associate your application with Microsoft Entra runtime.

For step-by-step instructions to register your application with Microsoft Entra ID, see Quickstart: Register an application with Microsoft Entra ID.

Important

Make note of the Directory (tenant) ID and the Application (client) ID. You will need these values to run the sample application.

Create a client secret

The application needs a client secret to prove its identity when requesting a token. In the same article linked earlier, see the Add a client secret section to create a client secret.

Important

Make note of the Client Secret. You will need it to run the sample application.

Assign Azure roles using the Azure portal

Assign one of the Azure Relay roles to the application's service principal at the desired scope (Relay entity, namespace, resource group, subscription). For detailed steps, see Assign Azure roles using the Azure portal.

Run the sample

1. Download the console application sample from GitHub.

2. Run the application locally on your computer per the instructions from the README article.

   Note

   Follow the same steps to run the sample console application for WCF Relay.

Highlighted code from the sample

Here's the code from the sample that shows how to use Microsoft Entra authentication to connect to the Azure Relay service.

1. Create a TokenProvider object by using the TokenProvider.CreateAzureActiveDirectoryTokenProvider method.

   If you haven't already created an app registration, see the Register your application with Microsoft Entra ID section to create it, and then create a client secret as mentioned in the Create a client secret section.

   If you want to use an existing app registration, follow these instructions to get Application (client) ID and Directory (tenant) ID.

   1. Sign in to the Azure portal.
   2. Search for and select Microsoft Entra ID using the search bar at the top.
   3. On the Microsoft Entra ID page, select App registrations in the Manage section on the left menu.
   4. Select your app registration.
   5. On the page for your app registration, you see the values for Application (client) ID and Directory (tenant) ID.

   To get the client secret, follow these steps:

   1. On the page your app registration, select Certificates & secrets on the left menu.
   2. Use the copy button in the Value column for the secret in the Client secrets section.

   static TokenProvider GetAadTokenProvider(string clientId, string tenantId, string clientSecret)
   {
       return TokenProvider.CreateAzureActiveDirectoryTokenProvider(
           async (audience, authority, state) =>
           {
               IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
                   .WithAuthority(authority)
                   .WithClientSecret(clientSecret)
                   .Build();
   
               var authResult = await app.AcquireTokenForClient(new [] { $"{audience}/.default" }).ExecuteAsync();
               return authResult.AccessToken;
           },
           $"https://login.microsoftonline.com/{tenantId}");
   }
   

2. Create a HybridConnectionListener or HybridConnectionClient object by passing the hybrid connection URI and the token provider you created in the previous step.

   Listener:

   var listener = new HybridConnectionListener(hybridConnectionUri, tokenProvider);    
   

   Sender:

   var sender = new HybridConnectionClient(hybridConnectionUri, tokenProvider);    
   

Samples

• Hybrid Connections: .NET, Java, JavaScript
• WCF Relay: .NET

Next steps

• 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:
  • Add or remove Azure role assignments using Azure PowerShell
  • Add or remove Azure role assignments using Azure CLI
  • Add or remove Azure role assignments using the REST API
  • Add or remove Azure role assignments using Azure Resource Manager Templates

To learn more about Azure Relay, see the following topics.

• What is Relay?
• Get started with Azure Relay Hybrid connections WebSockets
• Get stated with Azure Relay Hybrid connections HTTP requests