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. Em seguida, a função atribuída é verificada em relação às permissões definidas especificadas no arquivo de configuração para entender quais ações, campos e políticas estão disponíveis para essa função na entidade solicitada.

Funções

As funções definem o contexto de permissões no qual uma solicitação deve ser executada. Para cada entidade definida na configuração de runtime, você pode definir um conjunto de funções e permissões associadas que determinam como a entidade pode ser acessada nos pontos de extremidade REST e GraphQL.

O Construtor de API de Dados avalia as solicitações no contexto de uma única função:

• anonymous quando nenhum token de acesso é apresentado.
• authenticated quando um token de acesso válido é apresentado.
• <CUSTOM_USER_ROLE> quando um token de acesso válido é apresentado e o X-MS-API-ROLE cabeçalho HTTP é incluído especificando uma função de usuário que também está incluída na declaração do token de roles acesso.

As funções não são aditivas, o que significa que um usuário que é membro de ambos Role1 e Role2 não herda as permissões associadas a ambas as funções.

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 solicitante, independentemente da associação de função do solicitante indicada em seus tokens de acesso. Há duas funções do sistema: anonymous e authenticated.

Função de sistema anônima

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 token de acesso fornecido pelo aplicativo cliente deve incluir declarações de função que listam a associação de função de um usuário.
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" ]
        }
    ]
}

No Aplicativos Web Estáticos, um usuário é membro da função anônima por padrão. Se o usuário for autenticado, o usuário será membro das anonymous funções e authenticated .

Quando um aplicativo cliente envia uma solicitação autenticada para o Construtor de API de Dados implantado usando Aplicativos Web Estáticos conexões de banco de dados (versão prévia), o aplicativo cliente fornece um token de acesso que Aplicativos Web Estáticos se transforma em JSON:

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

Como o Construtor de API de Dados avalia solicitações no contexto de uma única função, ele avalia a solicitação no contexto da função authenticated do sistema 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. Um exemplo de solicitação, incluindo um token de acesso e X-MS-API-ROLE um cabeçalho HTTP:

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

Permissões

As permissões descrevem:

• Quem pode fazer solicitações em uma entidade com base na associação de função?
• 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.

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 o acesso de leitura não autenticado:

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

Para simplificar a definição de permissões em uma entidade, suponha que, se não houver permissões específicas para a authenticated função, as permissões definidas para a anonymous função serão usadas. A book configuração mostrada anteriormente permite que qualquer usuário anônimo ou autenticado execute operações de leitura na book entidade.

Quando as operações de leitura devem ser restritas somente 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 é 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 definidos pelo usuário são negados 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": [ "*" ]
  }]
}

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 com suporte para o tipo de entidade:

• Tabelas e exibições: 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 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 free-access seguir impede que os usuários na função executem operações de leitura em Column3. As referências a Column3 em solicitações GET (ponto de extremidade REST) ou consultas (GraphQL ponto de extremidade) 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" ]
              }
            }
          ]
        }
      ]
    }

Segurança no nível do item

As expressões de política de banco de dados permitem que os resultados sejam restritos ainda mais. As políticas de banco de dados convertem expressões em predicados de consulta executados no banco de dados. Há suporte para expressões de política de banco de dados para as seguintes ações:

Para obter mais informações sobre políticas de banco de dados, consulte a documentação do arquivo de configuração .

Exemplo

Uma política de banco de dados que restringe a ação read na consumer função para retornar apenas registros em que o título é "Título de exemplo".

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

Conteúdo relacionado

• Autenticação do Azure
• Autenticação local