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

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

Para ter uma função além de anonymous ou authenticated, o cabeçalho x-ms-api-role é necessário.

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 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 Serviço de Aplicativo, um usuário é membro da função anônima por padrão. Se o usuário estiver autenticado, será membro tanto da função anonymous quanto da função authenticated.

Como o Construtor de API de Dados avalia as 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. Uma solicitação de exemplo, 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 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.

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" ]
  }]
}

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 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": [ "*" ]
  }]
}

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" ]
              }
            }
          ]
        }
      ]
    }

Segurança em nível de 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 traduzem 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