Azure / Azure/data-api-builder

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

Offen
#3,276 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
2.x auth
Vorherrschende Sprache
C#
Sterne
1.5k
Forks
370
Ø Merge
3 T. 22 Std.
Gemergte PRs (30 T.)
9

Beschreibung

## 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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne bei der im Issue beschriebenen Authentifizierungskonfiguration und dem Befehl `dab configure --runtime.host.authentication.infer-role-from-claims`, und verfolge dann den Pfad zur Rollenauswahl der Anfrage. Als abgeschlossen gilt die Arbeit, wenn standardmäßig genau eine passende benutzerdefinierte Rolle sicher abgeleitet wird, bei null oder mehreren Treffern `authenticated` beibehalten wird, das Verhalten des Headers erhalten bleibt und das Deaktivieren dieser Funktion unterstützt wird.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
azure, csharp
Bereich
api, authentication, backend-api-design
Issue-Typ
Feature
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.