Azure / Azure/data-api-builder

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

Abierto
#3,276 0 comentarios 0 reacciones 0 asignados Ver en GitHub
2.x auth
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

Abrir la 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

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.