Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
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 authenticate 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 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 is recommended to grant the role to the most limited scope. Resources within it will inherit Azure RBAC roles assigned to the scope.
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
| Role | Description | Use case |
|---|---|---|
| Web PubSub Service Owner | Full access to data-plane APIs, including read/write REST APIs and Auth APIs. | Most commonly used for building an upstream server that handles negotiation requests and client events. |
| Web PubSub Service Reader | Readonly access to data-plane APIs. | Use it when write a monitoring tool that calls readonly REST APIs. |
Learn how to create a custom role if the built-in roles do not meet your requirements.
Azure custom roles: Steps to create a custom role
Next steps
To learn how to use Microsoft Entra authentication with role-based access control, see
- Authorize requests to Azure Web PubSub resources with Microsoft Entra applications
- Authorize requests to Azure Web PubSub resources with Managed identities for Azure resources
To learn more about roles-based access control, see
To learn how to disable the connection string and use only Microsoft Entra authentication, see