Azure / Azure/data-api-builder

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

Open
#3,276 0 comments 0 reactions 0 assignees View on GitHub
2.x auth
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.