Edit

Share via

Use wildcard group role patterns

Azure Web PubSub now supports wildcard pattern matching in client "group" roles so you can authorize a client for many related groups with a single role string.

You can continue to use the existing literal roles:

  • webpubsub.sendToGroup.{groupName}
  • webpubsub.joinLeaveGroup.{groupName}

But you can now also use the new pattern roles:

  • webpubsub.sendToGroups.{pattern}
  • webpubsub.joinLeaveGroups.{pattern}

Where {pattern} follows the wildcard syntax below.

When to use pattern roles

Use pattern roles when:

  • A user or device must access a large but bounded dynamic set of groups (for example: all groups for a specific tenant or project)
  • You want to keep access tokens small (avoid listing dozens or hundreds of explicit group roles)

Pattern syntax

Symbol Meaning
? Matches exactly one character except .
* Matches zero or more characters except .
** Matches zero or more characters including . (crosses segment boundaries)
\ Escape character for \, *, ?
. Acts as a hierarchy separator and is never matched by ? or * (only by **).

Additional rules:

  • Up to five total * characters (including those forming **) are allowed in a single pattern.

Examples

Pattern Matches Does not match
chat-* chat-1, chat-room chat.1, xchat-1
clientA.* clientA.alpha, clientA.1 clientA.alpha.room1, clientB.alpha
clientA.** clientA.alpha, clientA.alpha.room1 clientB.anything
clientA.rooms.?1 clientA.rooms.a1, clientA.rooms.11 clientA.rooms.1, clientA.rooms.a.1
literal\*star literal*star literalXstar

Escaping

Prefix *, ?, or \ with \ to match the literal character. Example: project\*123 matches only project*123.

Using pattern roles in code

Add the pattern role to the roles collection when generating a client access token. The client then automatically has the implied permissions for matching groups.

Code samples

const token = await serviceClient.getClientAccessToken({
  roles: [
    // Can send to all groups under clientA.
  'webpubsub.sendToGroups.clientA.**',
    // Can join/leave any direct child group under public.
  'webpubsub.joinLeaveGroups.public.*'
  ]
});

Security guidance

  • Prefer the narrowest pattern that satisfies the scenario.
  • Minimize the use of * to reduce over-permissioning risks.

Frequently asked questions

Q: Can I mix literal and pattern roles?

Yes. A literal role always applies exactly; patterns add broader coverage.

Next steps

Generate client access URL and use roles

  • Last updated on