Introducing Wildcard Roles in Azure Web PubSub: simpler, smarter permissions for real-time apps

Real-time interactivity is now a baseline expectation across industries, from collaborative dashboards to trading platforms, IoT monitoring, and live data visualizations. Developers need a way to broadcast data instantly to connected clients without worrying about connection management, scaling, or infrastructure.

That’s where Azure Web PubSub comes in. It provides a fully managed service that enables real-time messaging over WebSocket. Your applications can send and receive live updates instantly, without managing servers or message fan-out manually.

Now Azure Web PubSub is introducing a new capability that makes permission management simpler and more scalable: using wildcard pattern to define client permissions in groups.

Understanding Azure Web PubSub

Azure Web PubSub architecture showing client connections and message flow between backend and clients through the service. The dashed line indicates stateless APIs call, while the solid line indicates persistent, long-lived WebSocket connections.

Azure Web PubSub allows you to add real-time capabilities to your app. At a high level:

1. Your backend generates a client access token and hands it to a connecting client.
2. The client connects to Azure Web PubSub over WebSocket using that token.
3. Once connected, both the backend and client can send and receive messages through the service.
4. Clients can be organized into groups (for example, all clients in the same trading room or dashboard).

Groups allow you to target specific audiences efficiently: sending messages to all users in `dashboard.operations` or receiving updates from `market.NASDAQ.MSFT`.

To maintain security, every token defines a set of roles that specify what the client can do. The code illustrates what your backend needs to specify when generating a client access token for the scenarios mentioned.

// Arguments omitted for simplicity
const WebPubSubServiceClient = new WebPubSubServiceClient();
WebPubSubServiceClient.getClientAccessToken({ 
roles: [ 
"webpubsub.joinLeaveGroup.dashboard.operations",
"webpubsub.sendToGroups.dashboard.operations",
"webpubsub.sendToGroups.market.NASDAQ.MSFT",
],
});

The Current Permission Model: literal roles

Until now, Azure Web PubSub used literal group roles to define client permissions precisely.

For example:

roles: ["webpubsub.joinLeaveGroup.room123", "webpubsub.sendToGroup.room123"];

These roles are clear and secure: the client can only join and send to a specific group, `room123`.

However, as your application scales and dynamically creates many groups — for example, hundreds of trading accounts, projects, or classrooms — issuing one role per group becomes cumbersome. Your backend needs to:

• Track all the groups a user is authorized for
• Generate large tokens containing many role strings
• Refresh those tokens every time group access changes

The New Capability: wildcard patterns for group roles

Wildcard roles let you express permissions using patterns instead of individual hardcoded names. With a single role, you can authorize access to many related groups.

For example:

roles: ["webpubsub.joinLeaveGroups.room.*", "webpubsub.sendToGroups.room.*"];

This allows the client to join or send messages to any group whose name starts with `room:`.

Real-World Examples

Read the documentation for all supported wildcard patterns.

Why This Matters for Developers

Wildcard roles simplify the permission model for dynamic or large-scale systems:

• Simpler token management – You no longer need to issue or refresh tokens every time a client’s group list changes.
• Smaller tokens – One pattern replaces many literal roles, reducing token size.
• Dynamic authorization – When permissions for a client change (for example, they’re assigned to new groups that match existing patterns), there’s no need to regenerate tokens.

Deep Dive: financial trading platform

Let’s look at how wildcard roles can simplify real-time event management in a trading platform where financial assets, like stocks, are traded. See the complete code here. 

The Setup

The platform includes:

• A trading dashboard for managers of a trading team
• A trading dashboard for human traders on a trading team
• Two risk analysis bots:
  • A hardcoded risk bot that applies strict predefined rules
  • An LLM-based risk bot that uses AI to detect unusual behavior

On the platform, each trading account managed by one or more human traders, is given its own Web PubSub group:

• `account.1234.trades` – Trade updates
• `account.1234.orders` – Order events
• `market.NYSE` – Market data

The backend publishes events to these groups whenever a new order or trade occurs and clients that subscribe to these groups can receive real-time data.

Before: literal roles

Previously, each risk bot would need literal roles for every account:

roles: [
"webpubsub.joinLeaveGroup.account.1234.trades",
"webpubsub.joinLeaveGroup.account.5678.trades",
"webpubsub.joinLeaveGroup.account.9012.orders",
];

If new accounts were created, new tokens had to be issued to include their roles.

Now: wildcard roles

With the new feature, each risk bot can receive a single, compact token:

roles: [
"webpubsub.joinLeaveGroups.account.*",
"webpubsub.joinLeaveGroups.market.*",
];

Now, the bot automatically gains access to all existing and future account and market groups matching those patterns, without any token regeneration.

How the Risk Bots Work

When a trade event is published:

1. Both bots receive it in real time through wildcard subscriptions.
2. Each evaluates the event differently.
3. If a risk is detected, they publish an alert to `alerts.risk.*`.

Traders still receive messages for only their specific account group — using literal roles to ensure isolation:

roles: ["webpubsub.joinLeaveGroup.account.1234.trades"];

This demonstrates a clean separation:

• Automation and monitoring use wildcard roles for flexibility.
• End users use literal roles for strict access control.

Developer Experience: cleaner and more scalable

With wildcard roles, developers can design real-time architectures that are both expressive and efficient:

• Simplified token issuance
• Reduced backend logic for permission changes
• Better scalability for dynamic environments
• Flexible system-level actors (bots, dashboards, monitors)

Together, these improvements reduce operational complexity while keeping access control transparent and secure. Whether you’re building a trading platform, a game server, or a collaborative dashboard, this new capability helps you scale real-time systems with less friction and more control.