Azure / Azure/data-api-builder
[Enh]: Make `x-ms-api-role` optional
- Lenguaje dominante
- C#
- Estrellas
- 1.5k
- Forks
- 370
- Merge medio
- 3 d 22 h
- PR fusionados (30 d)
- 9
Descripción
## 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.
Guía de contribución
Línea de trabajo
Comienza por la configuración de autenticación y el comando `dab configure --runtime.host.authentication.infer-role-from-claims` descritos en el issue; después, sigue el flujo de selección del rol de la solicitud. El trabajo estará terminado cuando, de forma predeterminada, se infiera de manera segura exactamente un rol personalizado coincidente, cero o varias coincidencias dejen el valor `authenticated`, se conserve el comportamiento de la cabecera y se permita desactivar esta función.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- azure, csharp
- Área
- api, authentication, backend-api-design
- Tipo de issue
- Nueva funcionalidad
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Estancado
- Claridad
- Bastante claro
- Aptitud para principiantes
- 45/100