Azure / Azure/data-api-builder
[Enh]: Make `x-ms-api-role` optional
- Langage dominant
- C#
- Étoiles
- 1.5k
- Forks
- 370
- Merge moyen
- 3 j 22 h
- PR mergées (30 j)
- 9
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.
Guide de contribution
Ouvrir le guide de contribution
Piste de recherche
Commencez par la configuration d’authentification et la commande `dab configure --runtime.host.authentication.infer-role-from-claims` décrites dans l’issue, puis suivez le chemin de sélection du rôle de la requête. Le travail est terminé si, par défaut, exactement un rôle personnalisé correspondant est déduit de manière sûre, si zéro ou plusieurs correspondances laissent la valeur `authenticated`, si le comportement de l’en-tête est préservé et si la désactivation de cette fonctionnalité est prise en charge.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- azure, csharp
- Domaine
- api, authentication, backend-api-design
- Type d'issue
- Fonctionnalité
- Difficulté
- 4/5
- Temps estimé
- 3-5 jours
- Activité
- À l'abandon
- Clarté
- Plutôt claire
- Accessibilité débutants
- 45/100