Autorização e funções no construtor de API de Dados

O construtor de API de Dados usa um fluxo de trabalho de autorização baseado em função. Qualquer solicitação de entrada, autenticada ou não, é atribuída a uma função. As funções podem ser funções de sistema ou funções de usuário. Em seguida, a função atribuída é verificada em relação às permissões definidas especificadas na configuração para entender quais ações, campos e políticas estão disponíveis para essa função na entidade solicitada.

Determinando a função do usuário

Nenhuma função tem permissões padrão. Depois que o construtor de API de Dados determina uma função, a entidade permissions deve definir actions essa função para que a solicitação seja bem-sucedida.

A matriz de avaliação de função a seguir se aplica aos provedores de portador JWT (por exemplo, EntraID/AzureAD e Custom) onde o cliente envia Authorization: Bearer <token>.

Token de portador fornecido	X-MS-API-ROLE Fornecido	Função solicitada presente na declaração de token roles	Função/resultado efetivo
Não	Não	N/A	Anonymous
Sim (válido)	Não	N/A	Authenticated
Sim (válido)	Yes	Não	Rejeitado (403 Proibido)
Sim (válido)	Yes	Yes	Valor X-MS-API-ROLE
Sim (inválido)	Qualquer	N/A	Rejeitado (401 Não autorizado)

Para usar um papel diferente de Anonymous ou Authenticated, é necessário o cabeçalho X-MS-API-ROLE.

Observação

Uma solicitação pode ser associada a muitas funções na entidade principal autenticada. No entanto, o construtor de API de Dados avalia as permissões e as políticas no contexto de exatamente uma função efetiva. Quando fornecido, o X-MS-API-ROLE cabeçalho seleciona qual função é usada.

Notas do provedor:

• Provedores EasyAuth (por exemplo, AppService): a autenticação pode ser estabelecida por cabeçalhos injetados por plataforma (como X-MS-CLIENT-PRINCIPAL) em vez de um token de portador.
• Simulator: as solicitações são tratadas como autenticadas para desenvolvimento/teste, sem validar um token real.

Funções de sistema

As funções do sistema são funções internas reconhecidas pelo construtor de API de Dados. Uma função do sistema é atribuída automaticamente a um solicitante, independentemente da associação de função do solicitante indicada em seus tokens de acesso. Há duas funções de sistema: Anonymous e Authenticated.

Função do sistema anônimo

A função do Anonymous sistema é atribuída a solicitações executadas por usuários não autenticados. As entidades definidas pela configuração de runtime devem incluir permissões para a Anonymous função se o acesso não autenticado for desejado.

Exemplo

A seguinte configuração de runtime do Construtor de API de Dados demonstra explicitamente a configuração da função Anonymous do sistema para incluir o acesso de leitura à entidade Book:

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

Quando um aplicativo cliente envia uma solicitação acessando a entidade Book em nome de um usuário não autenticado, o aplicativo não deve incluir o Authorization cabeçalho HTTP.

Função do sistema autenticado

A função do Authenticated sistema é atribuída a solicitações executadas por usuários autenticados.

Exemplo

A seguinte configuração de runtime do Construtor de API de Dados demonstra explicitamente a configuração da função Authenticated do sistema para incluir o acesso de leitura à entidade Book:

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

Funções de usuário

As funções de usuário são funções não sistema que são atribuídas aos usuários dentro do provedor de identidade definido na configuração de runtime. Para que o construtor de API de Dados avalie uma solicitação no contexto de uma função de usuário, dois requisitos devem ser atendidos:

1. O principal autenticado deve incluir declarações de roles que listam a associação de uma função de usuário (por exemplo, a declaração JWT roles).
2. O aplicativo cliente deve incluir o cabeçalho X-MS-API-ROLE HTTP com solicitações e definir o valor do cabeçalho como a função de usuário desejada.

Exemplo de avaliação de função

O exemplo a seguir demonstra as Book solicitações feitas à entidade configurada na configuração de runtime do Construtor de API de Dados da seguinte maneira:

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

O Construtor de API de Dados avalia as solicitações no contexto de uma única função efetiva. Se uma solicitação for autenticada e nenhum cabeçalho X-MS-API-ROLE for fornecido, o Data API builder avaliará a solicitação no contexto da função do sistema Authenticated por padrão.

Se a solicitação do aplicativo cliente também incluir o cabeçalho X-MS-API-ROLE HTTP com o valor author, a solicitação será avaliada no contexto da author função. Uma solicitação de exemplo, incluindo um token de acesso e X-MS-API-ROLE um cabeçalho HTTP:

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

Importante

A solicitação de um aplicativo cliente é rejeitada quando a declaração do token de roles acesso fornecido não contém a função listada no X-MS-API-ROLE cabeçalho.

Permissões

As permissões descrevem:

• Quem pode fazer solicitações em uma entidade com base na associação a um papel?
• Quais ações (criar, ler, atualizar, excluir, executar) um usuário pode executar?
• Quais campos são acessíveis para uma ação específica?
• Quais restrições extras existem nos resultados retornados por uma solicitação?

A sintaxe para definir permissões é descrita no artigo de configuração de runtime.

Importante

Pode haver várias funções definidas na configuração de permissões de uma única entidade. No entanto, uma solicitação só é avaliada no contexto de uma única função:

• Por padrão, a função Anonymous do sistema ou Authenticated
• Quando a função está incluída, é definida no cabeçalho HTTP X-MS-API-ROLE.

Segurança por padrão

Por padrão, uma entidade não tem permissões configuradas, o que significa que ninguém pode acessar a entidade. Além disso, o construtor de API de Dados ignora objetos de banco de dados quando eles não são referenciados na configuração de runtime.

As permissões devem ser configuradas explicitamente

Para permitir o acesso não autenticado a uma entidade, a Anonymous função deve ser definida explicitamente nas permissões da entidade. Por exemplo, as book permissões da entidade são definidas explicitamente para permitir acesso de leitura não autenticado:

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

Se você quiser que usuários não autenticados e autenticados tenham acesso, conceda explicitamente permissões a funções do sistema (Anonymous e Authenticated).

Quando as operações de leitura devem ser restritas somente a usuários autenticados, a configuração de permissões a seguir deve ser definida, resultando na rejeição de solicitações não autenticadas:

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

Uma entidade não requer e não está preconfigurada com permissões para as funções Anonymous e Authenticated. Uma ou mais funções de usuário podem ser definidas na configuração de permissões de uma entidade e todas as outras funções indefinidas, sistema ou usuário definidos são automaticamente negadas ao acesso.

No exemplo a seguir, a função administrator de usuário é a única função definida para a book entidade. Um usuário deve ser membro da administrator função e incluir essa função no X-MS-API-ROLE cabeçalho HTTP para operar na book entidade:

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

Observação

Para impor o controle de acesso para consultas GraphQL ao usar o construtor de API de Dados com o Azure Cosmos DB, você deve usar a @authorize diretiva no arquivo de esquema graphQL fornecido. No entanto, para mutações e filtros do GraphQL em consultas GraphQL, a configuração de permissões ainda impõe o controle de acesso, conforme descrito anteriormente.

Ações

As ações descrevem a acessibilidade de uma entidade dentro do escopo de uma função. As ações podem ser especificadas individualmente ou com o atalho curinga: * (asterisco). O atalho curinga representa todas as ações suportadas para o tipo de entidade:

• Tabelas e exibições: create, , read, updatedelete
• Procedimentos armazenados: execute

Para obter mais informações sobre ações, consulte a documentação do arquivo de configuração .

Acesso a campo

Você pode configurar quais campos devem ser acessíveis para uma ação. Por exemplo, você pode definir quais campos incluir e excluir da ação read .

O exemplo a seguir impede que os usuários na free-access função executem operações de leitura em Column3. As referências a Column3 em solicitações GET (endpoint REST) ou consultas (endpoint GraphQL) resultam em uma solicitação rejeitada:

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

Observação

Para impor o controle de acesso para consultas GraphQL ao usar o construtor de API de Dados com o Azure Cosmos DB, você deve usar a @authorize diretiva no arquivo de esquema graphQL fornecido. No entanto, para mutações e filtros do GraphQL em consultas GraphQL, a configuração de permissões ainda impõe o controle de acesso, conforme descrito aqui.

Segurança em nível de item

As políticas de banco de dados permitem filtrar os resultados no nível da linha. As políticas se traduzem em predicados de consulta que o banco de dados avalia, garantindo que os usuários acessem apenas registros autorizados.

Ações com suporte	Sem suporte
read, update, delete	create, execute

Observação

Atualmente, o Azure Cosmos DB para NoSQL não dá suporte a políticas de banco de dados.

Para obter etapas de configuração detalhadas, referência de sintaxe e exemplos, consulte Configurar políticas de banco de dados.

Exemplo rápido

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

Conteúdo relacionado

• Configurar políticas de banco de dados para filtragem em nível de linha
• Configurar a autenticação da ID do Microsoft Entra
• Configurar a autenticação do Simulador para testes locais