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 do Sistema ou Funções de Usuário. A função atribuída é então 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 predefinidas. Uma vez que o Data API Builder determine uma função, a entidade permissions deve definir actions para essa função para que o pedido seja bem-sucedido.

A seguinte matriz de avaliação de funções aplica-se a fornecedores portadores JWT (por exemplo, EntraID/AzureAD e Custom), onde o cliente envia .Authorization: Bearer <token>

Token de portador fornecido	X-MS-API-ROLE fornecido	Papel solicitado presente na reivindicação do token roles	Papel efetivo / resultado
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	X-MS-API-ROLE valor
Sim (inválido)	Qualquer	N/A	Rejeitado (401 Não Autorizado)

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

Observação

Um pedido pode estar associado a várias funções no principal autenticado. No entanto, o Data API builder avalia permissões e políticas no contexto de exatamente um papel eficaz. Quando fornecido, o X-MS-API-ROLE cabeçalho seleciona qual o papel a ser usado.

Notas do prestador:

• Fornecedores EasyAuth (por exemplo, AppService): a autenticação pode ser estabelecida por cabeçalhos injetados pela plataforma (como X-MS-CLIENT-PRINCIPAL) em vez de um token portador.
• Simulator: os pedidos são tratados como autenticados para desenvolvimento/testes, sem validação de um token real.

Funções do 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 requerente, independentemente da associação de função do requerente indicada nos seus tokens de acesso. Existem duas funções do sistema: Anonymous e Authenticated.

Função anônima do sistema

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

Exemplo

A seguinte configuração de tempo de execução do construtor de API de Dados demonstra explicitamente a configuração da função Anonymous do sistema para incluir acesso de leitura à entidade Livro:

"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 autenticada

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

Exemplo

A seguinte configuração de tempo de execução do construtor de API de Dados demonstra explicitamente a configuração da função Authenticated do sistema para incluir acesso de leitura à entidade Livro:

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

Funções do usuário

As funções de usuário são funções que não são do sistema atribuídas a usuários dentro do provedor de identidade definido na configuração de tempo de execução. 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 reivindicações de função que listem a pertença ao papel do utilizador (por exemplo, a reivindicaçã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ções

O exemplo a seguir demonstra as solicitações feitas à entidade configurada Book na configuração de tempo de execução 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 Data API Builder avalia pedidos no contexto de um único papel eficaz. Se um pedido for autenticado e não for fornecido um cabeçalho X-MS-API-ROLE, o Data API builder avalia o pedido, por padrão, no contexto do papel do sistema Authenticated.

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. Um exemplo de solicitação 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 X-MS-API-ROLE no cabeçalho.

Permissões

As permissões descrevem:

• Quem pode fazer solicitações em uma entidade com base no pertencimento a uma função?
• Que ações (criar, ler, atualizar, excluir, executar) um usuário pode executar?
• Que campos estão acessíveis para uma determinada ação?
• Que restrições adicionais existem sobre os resultados devolvidos por um pedido?

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

Importante

Pode haver várias funções definidas dentro da configuração de permissões de uma única entidade. No entanto, um pedido só é avaliado no contexto de uma única função:

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

Proteger por predefiniçã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 tempo de execução.

As permissões devem ser configuradas explicitamente

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

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

Se quiser que tanto os utilizadores não autenticados como os autenticados tenham acesso, conceda explicitamente permissões a ambos os papéis do sistema (Anonymous e Authenticated).

Quando as operações de leitura devem ser restritas apenas a usuários autenticados, a seguinte configuração de permissões 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á pré-configurada com permissões para as Anonymous funções e Authenticated . Uma ou mais funções de usuário podem ser definidas dentro da configuração de permissões de uma entidade e todas as outras funções indefinidas, sistema ou usuário definido, têm acesso negado automaticamente.

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 controlo de acesso para consultas GraphQL ao usar o Data API builder com Azure Cosmos DB, deve usar a @authorize diretiva no ficheiro de esquema GraphQL fornecido. No entanto, para mutações e filtros GraphQL em consultas GraphQL, a configuração de permissões ainda impõe controlo de acesso conforme descrito anteriormente.

Ações

As ações descrevem a acessibilidade de uma entidade no âmbito 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 Vistas: create, read, update, delete
• Procedimentos armazenados: execute

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

Acesso ao campo

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

O exemplo a seguir impede que os usuários na free-access função executem operações de leitura no Column3. Referências a Column3 em solicitações GET (ponto de extremidade REST) ou consultas (ponto de extremidade GraphQL) resultam em um pedido rejeitado:

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

Observação

Para impor controlo de acesso para consultas GraphQL ao usar o Data API builder com Azure Cosmos DB, deve usar a @authorize diretiva no ficheiro de esquema GraphQL fornecido. No entanto, para mutações e filtros GraphQL em consultas GraphQL, a configuração de permissões continua a impor controlo de acesso conforme descrito aqui.

Segurança ao nível do item

As políticas de base de dados permitem filtrar resultados ao nível da linha. As políticas traduzem-se em predicados de consulta que a base de dados avalia, garantindo que os utilizadores acedam apenas a registos autorizados.

Ações suportadas	Não suportado
read, update, delete	create, execute

Observação

O Azure Cosmos DB para NoSQL atualmente não suporta políticas de base de dados.

Para passos de configuração detalhados, referência sintáctica e exemplos, veja Configurar políticas de base de dados.

Exemplo rápido

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

Conteúdo relacionado

• Configurar políticas de base de dados para filtragem ao nível das linhas
• Configurar autenticação do ID Microsoft Entra
• Configurar autenticação do Simulador para testes locais