[Enh]: Make `x-ms-api-role` optional

[JerryNixon]

What?

Automatically elevate an authenticated request to a custom role.

Important

This feature does not change the paradigm of one role per request.

Current behavior

A request with a valid token is automatically assigned the authenticated role. If the token includes one or more custom roles, the request may include the x-ms-api-role HTTP header with the value of any role that is also present in the token's claims in order to elevate from authenticated to that custom role. There is no check if the custom role exists in DAB configuration.

Desired behavior

If an authenticated request's token contains exactly one role, and that role matches any configured, custom role in DAB, automatically elevate the request to that role; otherwise, remain authenticated.

flowchart TD
A[Request] --> B{Token?}

B -->|No| ANON[Role: anonymous]

B -->|Yes| C{Valid?}
C -->|No| REJ[Reject]
C -->|Yes| D{Has roles?}

D -->|No| AUTH[Role: authenticated]

D -->|Yes| P[Begin]

P --> E[Get token roles]
P --> F[Get DAB roles]

E --> G[Intersect]
F --> G

G --> H{Count<br/>Overlap}

H -->|None| AUTH
H -->|One| ROLE[Role: custom]
H -->|More| AUTH

ANON --> END@{ shape: stadium, label: "End and Continue" }
AUTH --> END
ROLE --> END

Loading

Why?

The x-ms-api-role header is unnecessary overhead when there is only one custom role in the bearer token — or only one custom role that matches the DAB configuration. In these cases, the intended role is unambiguous and should be assigned automatically.

Note

When multiple roles overlap, the caller can use the x-ms-api-role HTTP header to disambiguate. This preserves the existing mechanism for advanced scenarios and lets callers establish their own ordering precedent.

How?

This is our new default behavior, but developers can still opt-out.

Configuration

      "authentication": {
        "provider": "EntraId",
        "infer-role-from-claims": true // default: true
      },

Command line

dab configure --runtime.host.authentication.infer-role-from-claims true

Design goals

• Safe by default — auto-elevation occurs only when there is exactly one matching role, eliminating ambiguity around role and policy selection.
• Non-breaking — existing behavior is unchanged. Requests that include x-ms-api-role continue to work as they do today.
• Simple to reason about — the logic is deterministic: one match → auto-assign; zero or many → do nothing.