Compartir a través de

Autorización y roles en data API Builder

  • Artículo

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 el archivo de configuración para comprender qué acciones, campos y directivas están disponibles para ese rol en la entidad solicitada.

Roles

Los roles establecen el contexto de permisos en el que se debe ejecutar una solicitud. Para cada entidad definida en la configuración en tiempo de ejecución, puede definir un conjunto de roles y permisos asociados que determinen cómo se puede acceder a la entidad en los puntos de conexión REST y GraphQL.

El generador de API de datos evalúa las solicitudes en el contexto de un único rol:

  • anonymous cuando no se presenta ningún token de acceso.
  • authenticated cuando se presenta un token de acceso válido.
  • <CUSTOM_USER_ROLE> cuando se presenta un token de acceso válido y el X-MS-API-ROLE encabezado HTTP se incluye especificando un rol de usuario que también se incluye en la notificación del token de roles acceso.

Los roles no son aditivos, lo que significa que un usuario que es miembro de ambos Role1 y Role2 no hereda los permisos asociados a ambos roles.

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 a roles 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 no del sistema que se asignan a los usuarios dentro del proveedor de identidades establecido 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. El token de acceso proporcionado por la aplicación cliente debe incluir notificaciones de rol que enumeran la pertenencia a roles de un usuario.
  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" ]
        }
    ]
}

En Static Web Apps, un usuario es miembro del rol anónimo de forma predeterminada. Si el usuario está autenticado, el usuario es miembro de los anonymous roles y authenticated .

Cuando una aplicación cliente envía una solicitud autenticada a Data API Builder implementada mediante Static Web Apps conexione de base de datos (versión preliminar), la aplicación cliente proporciona un token de acceso que Static Web Apps transforma en JSON:

{
  "identityProvider": "azuread",
  "userId": "d75b260a64504067bfc5b2905e3b8182",
  "userDetails": "username",
  "userRoles": ["anonymous", "authenticated", "author"]
}

Dado que data API Builder evalúa las solicitudes en el contexto de un solo rol, evalúa la solicitud en el contexto del rol authenticated del 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 que incluye un token de acceso y X-MS-API-ROLE un encabezado HTTP:

curl -k -r 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 notificación del token de roles acceso proporcionado no contiene el rol enumerado en el X-MS-API-ROLE encabezado.

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 único rol:

  • De forma predeterminada, el rol anonymous del sistema o authenticated
  • Cuando se incluye, el rol establecido 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 en tiempo 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" ]
  }]
}

Para simplificar la definición de permisos en una entidad, suponga que si no hay permisos específicos para el authenticated rol, se usan los permisos definidos para el anonymous rol. La book configuración mostrada anteriormente permite que los usuarios anónimos o autenticados realicen operaciones de lectura en la book entidad.

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 y no está preconfigurada con permisos para los anonymous roles y authenticated . Uno o varios roles de usuario se pueden definir dentro de la configuración de permisos de una entidad y todos los demás roles, sistema o usuario definidos sin definir, se deniegan 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 administrator rol e incluir ese rol en el X-MS-API-ROLE encabezado HTTP para operar en la book entidad:

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

Nota

Para aplicar el control de acceso para las consultas graphQL al usar Data API Builder con Azure Cosmos DB, debe usar la directiva en el @authorizearchivo de esquema graphQL proporcionado. Sin embargo, en el caso de las mutaciones y filtros de GraphQL en las consultas de GraphQL, el control de acceso sigue siendo aplicado por la configuración de permisos tal y 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 con el método abreviado de caracteres comodín: * (asterisco). El método abreviado de caracteres comodín representa 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 como resultado 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 graphQL al usar Data API Builder con Azure Cosmos DB, debe usar la directiva en el @authorizearchivo de esquema graphQL proporcionado. Sin embargo, para las mutaciones y filtros de GraphQL en las consultas de GraphQL, el control de acceso todavía se aplica mediante la configuración de permisos tal y como se describe aquí.

Seguridad de nivel de elemento

Las expresiones de directiva de base de datos permiten restringir aún más los resultados. Las directivas de base de datos traducen expresiones a predicados de consulta ejecutados en la base de datos. Las expresiones de directiva de base de datos se admiten para las siguientes acciones:

  • create
  • leer
  • actualización
  • eliminar

Advertencia

La acción de ejecución , que se usa con procedimientos almacenados, no admite directivas de base de datos.

Nota

Las directivas de base de datos no son compatibles actualmente con CosmosDB para NoSQL.

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

Ejemplo

Una directiva de base de datos que restringe la read acción en el consumer rol para devolver solo los registros en los que el título es "Título de ejemplo".

{
  "role": "consumer",
  "actions": [
    {
      "action": "read",
      "policy": {
        "database": "@item.title eq 'Sample Title'"
      }
    }
  ]
}

Contenido relacionado