Azure / Azure/data-api-builder

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

Ouverte
#3,276 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub
2.x auth
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

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.