Autorización y roles en Data API Builder

Data API Builder usa un flujo de trabajo de autorización basado en roles. Cualquier solicitud entrante, autenticada o no, se asigna a un rol. Los roles pueden ser roles de sistema o roles de usuario. A continuación, el rol asignado se comprueba con los permisos definidos especificados en la configuración para comprender qué acciones, campos y directivas están disponibles para ese rol en la entidad solicitada.

Determinar el rol del usuario

Ningún rol tiene permisos predeterminados. Una vez que Data API Builder determina un rol, permissions de la entidad debe definir actions para que ese rol tenga éxito en la solicitud.

La siguiente matriz de evaluación de roles se aplica a los proveedores de portadores JWT (por ejemplo, EntraID/AzureAD y Custom) donde el cliente envía .Authorization: Bearer <token>

Token de portador proporcionado	X-MS-API-ROLE proporcionado	Rol solicitado presente en la reclamación del token roles	Rol o resultado efectivos
No	No	N/A	Anonymous
Sí (válido)	No	N/A	Authenticated
Sí (válido)	Sí	No	Rechazado (403 Prohibido)
Sí (válido)	Sí	Sí	X-MS-API-ROLE valor
Sí (no válido)	Cualquiera	N/A	Rechazado (401 No autorizado)

Para usar un rol distinto de Anonymous o Authenticated, se requiere el X-MS-API-ROLE encabezado .

Nota:

Una solicitud se puede asociar a muchos roles en el principal autenticado. Sin embargo, Data API builder evalúa los permisos y las directivas exactamente en el contexto de un rol efectivo. Cuando se proporciona, el X-MS-API-ROLE encabezado selecciona qué rol se usa.

Notas del proveedor:

• Proveedores de EasyAuth (por ejemplo, AppService): la autenticación se puede establecer mediante encabezados insertados por la plataforma (como X-MS-CLIENT-PRINCIPAL) en lugar de un token de portador.
• Simulator: las solicitudes se tratan como autenticadas para el desarrollo o las pruebas, sin validar un token real.

Roles del sistema

Los roles del sistema son roles integrados reconocidos por Data API Builder. Un rol del sistema se asigna automáticamente a un solicitante, independientemente de la pertenencia al rol del solicitante que se indica en sus tokens de acceso. Hay dos roles de sistema: Anonymous y Authenticated.

Rol de sistema anónimo

El Anonymous rol del sistema se asigna a las solicitudes ejecutadas por usuarios no autenticados. Las entidades definidas por la configuración en tiempo de ejecución deben incluir permisos para el Anonymous rol si se desea el acceso no autenticado.

Ejemplo

La siguiente configuración del entorno de ejecución de Data API Builder muestra la configuración explícita del rol Anonymous del sistema para incluir el acceso de lectura a la entidad Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Anonymous",
            "actions": [ "read" ]
        }
    ]
}

Cuando una aplicación cliente envía una solicitud que accede a la entidad Book en nombre de un usuario no autenticado, la aplicación no debe incluir el Authorization encabezado HTTP.

Rol de sistema autenticado

El Authenticated rol del sistema se asigna a las solicitudes ejecutadas por usuarios autenticados.

Ejemplo

La siguiente configuración del entorno de ejecución de Data API Builder muestra la configuración explícita del rol Authenticated del sistema para incluir el acceso de lectura a la entidad Book:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "Authenticated",
            "actions": [ "read" ]
        }
    ]
}

Roles de usuario

Los roles de usuario son roles que no son de sistema que se asignan a los usuarios dentro del proveedor de identidades que estableció en la configuración del entorno de ejecución. Para que data API Builder evalúe una solicitud en el contexto de un rol de usuario, se deben cumplir dos requisitos:

1. La entidad de seguridad autenticada debe incluir notificaciones de rol que enumeran la pertenencia a roles de un usuario (por ejemplo, la notificación JWT roles ).
2. La aplicación cliente debe incluir el encabezado X-MS-API-ROLE HTTP con solicitudes y establecer el valor del encabezado como rol de usuario deseado.

Ejemplo de evaluación de roles

En el ejemplo siguiente se muestran las solicitudes realizadas a la Book entidad configurada en la configuración del entorno de ejecución del Generador de API de datos de la siguiente manera:

"Book": {
    "source": "books",
    "permissions": [
        {
      "role": "Anonymous",
            "actions": [ "read" ]
        },
        {
      "role": "Authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

El generador de API de datos evalúa las solicitudes en el contexto de un único rol efectivo. Si se autentica una solicitud y no se proporciona ningún X-MS-API-ROLE encabezado, Data API Builder evalúa la solicitud en el contexto del rol del Authenticated sistema de forma predeterminada.

Si la solicitud de la aplicación cliente también incluye el encabezado X-MS-API-ROLE HTTP con el valor author, la solicitud se evalúa en el contexto del author rol. Una solicitud de ejemplo, incluido un token de acceso y X-MS-API-ROLE un encabezado HTTP:

curl -k -X GET \
  -H 'Authorization: Bearer ey...' \
  -H 'X-MS-API-ROLE: author' \
  https://localhost:5001/api/Book

Importante

La solicitud de una aplicación cliente se rechaza cuando la reclamación del token de acceso suministrado no contiene el rol enumerado en el encabezado roles.

Permisos

Los permisos describen:

• ¿Quién puede realizar solicitudes en una entidad basada en la pertenencia a roles?
• ¿Qué acciones (crear, leer, actualizar, eliminar, ejecutar) puede realizar un usuario?
• ¿Qué campos son accesibles para una acción determinada?
• ¿Qué restricciones adicionales existen en los resultados devueltos por una solicitud?

La sintaxis para definir permisos se describe en el artículo configuración del entorno de ejecución.

Importante

Puede haber varios roles definidos dentro de la configuración de permisos de una sola entidad. Sin embargo, una solicitud solo se evalúa en el contexto de un solo rol:

• De forma predeterminada, el rol Anonymous del sistema o Authenticated
• Cuando se incluye, el rol se establece en el X-MS-API-ROLE encabezado HTTP.

Seguro de forma predeterminada

De forma predeterminada, una entidad no tiene permisos configurados, lo que significa que nadie puede acceder a la entidad. Además, data API Builder omite los objetos de base de datos cuando no se hace referencia a ellos en la configuración del entorno de ejecución.

Los permisos deben configurarse explícitamente

Para permitir el acceso no autenticado a una entidad, el Anonymous rol debe definirse explícitamente en los permisos de la entidad. Por ejemplo, los permisos de la book entidad se establecen explícitamente para permitir el acceso de lectura no autenticado:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Anonymous",
    "actions": [ "read" ]
  }]
}

Si desea que los usuarios no autenticados y autenticados tengan acceso, conceda explícitamente permisos a ambos roles del sistema (Anonymous y Authenticated).

Cuando las operaciones de lectura solo deben restringirse a los usuarios autenticados, se debe establecer la siguiente configuración de permisos, lo que da lugar al rechazo de solicitudes no autenticadas:

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "Authenticated",
    "actions": [ "read" ]
  }]
}

Una entidad no requiere ni está preconfigurada con permisos para los roles Anonymous y Authenticated. Uno o varios roles de usuario se pueden definir dentro de la configuración de permisos de una entidad, y a todos los demás roles, ya sean del sistema o definidos por el usuario y no especificados, se les deniega automáticamente el acceso.

En el ejemplo siguiente, el rol administrator de usuario es el único rol definido para la book entidad. Un usuario debe ser miembro del rol administrator e incluir ese rol dentro del encabezado HTTP X-MS-API-ROLE para operar sobre la entidad book.

"book": {
  "source": "dbo.books",
  "permissions": [{
    "role": "administrator",
    "actions": [ "*" ]
  }]
}

Nota:

Para aplicar el control de acceso para las consultas de GraphQL al usar Data API Builder con Azure Cosmos DB, debe usar la directiva en el @authorizearchivo de esquema de GraphQL proporcionado. Sin embargo, en el caso de las mutaciones y filtros de GraphQL en las consultas de GraphQL, la configuración de permisos sigue aplicando el control de acceso, tal como se ha descrito anteriormente.

Acciones

Las acciones describen la accesibilidad de una entidad dentro del ámbito de un rol. Las acciones se pueden especificar individualmente o utilizando el comodín: * (asterisco). El atajo comodín indica todas las acciones admitidas para el tipo de entidad.

• Tablas y vistas: create, read, update, delete
• Procedimientos almacenados: execute

Para obtener más información sobre las acciones, consulte la documentación del archivo de configuración .

Acceso a campos

Puede configurar qué campos deben ser accesibles para una acción. Por ejemplo, puede establecer los campos que se van a incluir y excluir de la read acción.

En el ejemplo siguiente se impide que los usuarios del free-access rol realicen operaciones de lectura en Column3. Las referencias a Column3 en solicitudes GET (punto de conexión REST) o consultas (punto de conexión GraphQL) dan lugar a una solicitud rechazada.

    "book": {
      "source": "dbo.books",
      "permissions": [
        {
          "role": "free-access",
          "actions": [
            "create",
            "update",
            "delete",
            {
              "action": "read",
              "fields": {
                "include": [ "Column1", "Column2" ],
                "exclude": [ "Column3" ]
              }
            }
          ]
        }
      ]
    }

Nota:

Para aplicar el control de acceso para las consultas de GraphQL al usar Data API Builder con Azure Cosmos DB, debe usar la directiva en el @authorizearchivo de esquema de GraphQL proporcionado. Sin embargo, para las mutaciones y filtros de GraphQL en las consultas de GraphQL, la configuración de permisos sigue aplicando el control de acceso, tal como se describe aquí.

Seguridad de nivel de elemento

Las directivas de base de datos permiten filtrar los resultados en el nivel de fila. Las directivas se traducen en predicados de consulta que evalúa la base de datos, lo que garantiza que los usuarios accedan solo a los registros autorizados.

Acciones admitidas	No está soportado
read, , update, delete	create, execute

Nota:

Azure Cosmos DB para NoSQL no admite actualmente directivas de base de datos.

Para obtener pasos de configuración detallados, referencia de sintaxis y ejemplos, consulte Configuración de directivas de base de datos.

Ejemplo rápido

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.ownerId eq @claims.userId"
      }
    }
  ]
}

Contenido relacionado

• Configuración de directivas de base de datos para el filtrado de nivel de fila
• Configuración de la autenticación de Microsoft Entra ID
• Configuración de la autenticación del simulador para pruebas locales