Azure / Azure/data-api-builder
[Enh]: Make `x-ms-api-role` optional
- Dominant language
- C#
- Stars
- 1.5k
- Forks
- 370
- Avg merge
- 3d 17h
- Merged PRs (30d)
- 8
Description
## 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`.
```mermaid
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
Overlap}
H -->|None| AUTH
H -->|One| ROLE[Role: custom]
H -->|More| AUTH
ANON --> END@{ shape: stadium, label: "End and Continue" }
AUTH --> END
ROLE --> END
```
## 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
```json
"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.
Contributor guide
Assessment
This issue has not been assessed yet.