Authorize access to Web PubSub resources using Microsoft Entra ID

Article
08/17/2023

The Azure Web PubSub Service enables the authorization of requests to Azure Web PubSub resources by utilizing Microsoft Entra ID.

By utilizing role-based access control (RBAC) with Microsoft Entra ID, permissions can be granted to a security principal^[1]. Microsoft Entra authorizes this security principal and returns an OAuth 2.0 token, which Web PubSub resources can then use to authorize a request.

Using Microsoft Entra ID for authorization of Web PubSub requests offers improved security and ease of use compared to Access Key authorization. Microsoft recommends utilizing Microsoft Entra authorization with Web PubSub resources when possible to ensure access with the minimum necessary privileges.

[1] security principal: a user/resource group, an application, or a service principal such as system-assigned identities and user-assigned identities.

Overview of Microsoft Entra ID for Web PubSub

Authentication is necessary to access a Web PubSub resource when using Microsoft Entra ID. This authentication involves two steps:

First, Azure authenticates the security principal and issues an OAuth 2.0 token.
Second, the token is added to the request to the Web PubSub resource. The Web PubSub service uses the token to check if the service principal has the access to the resource.

Client-side authentication while using Microsoft Entra ID

The negotiation server/Function App shares an access key with the Web PubSub resource, enabling the Web PubSub service to authenticate client connection requests using client tokens generated by the access key.

However, access key is often disabled when using Microsoft Entra ID to improve security.

To address this issue, we have developed a REST API that generates a client token. This token can be used to connect to the Azure Web PubSub service.

To use this API, the negotiation server must first obtain an Microsoft Entra Token from Azure to authenticate itself. The server can then call the Web PubSub Auth API with the Microsoft Entra Token to retrieve a Client Token. The Client Token is then returned to the client, who can use it to connect to the Azure Web PubSub service.

We provided helper functions (for example `GenerateClientAccessUri) for supported programming languages.

Assign Azure roles for access rights

Microsoft Entra authorizes access rights to secured resources through Azure role-based access control. Azure Web PubSub defines a set of Azure built-in roles that encompass common sets of permissions used to access Web PubSub resources. You can also define custom roles for access to Web PubSub resources.

Resource scope

Before assigning an Azure RBAC role to a security principal, it's important to identify the appropriate level of access that the principal should have. It's recommended to grant the role with the narrowest possible scope. Resources located underneath inherit Azure RBAC roles with broader scopes.

You can scope access to Azure Web PubSub resources at the following levels, beginning with the narrowest scope:

An individual resource.

At this scope, a role assignment applies to only the target resource.
A resource group.

At this scope, a role assignment applies to all of the resources in the resource group.
A subscription.

At this scope, a role assignment applies to all of the resources in all of the resource groups in the subscription.
A management group.

At this scope, a role assignment applies to all of the resources in all of the resource groups in all of the subscriptions in the management group.

Azure built-in roles for Web PubSub resources

Web PubSub Service Owner

Full access to data-plane permissions, including read/write REST APIs and Auth APIs.

This role is the most common used for building an upstream server.
Web PubSub Service Reader

Use to grant read-only REST APIs permissions to Web PubSub resources.

It's used when you'd like to write a monitoring tool that calling ONLY Web PubSub data-plane READONLY REST APIs.