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

O construtor de API de Dados utiliza um fluxo de trabalho de autorização baseado em funções. Qualquer pedido recebido, autenticado ou não, é atribuído a uma função. As funções podem ser Funções de Sistema ou Funções de Utilizador. Em seguida, a função atribuída é verificada em relação às permissões definidas especificadas no ficheiro de configuração para compreender que ações, campos e políticas estão disponíveis para essa função na entidade pedida.

Funções

As funções definem o contexto de permissões no qual um pedido deve ser executado. Para cada entidade definida na configuração de runtime, pode definir um conjunto de funções e permissões associadas que determinam como a entidade pode ser acedida nos pontos finais REST e GraphQL.

O construtor de API de Dados avalia os pedidos no contexto de uma única função:

• anonymous quando não é apresentado nenhum token de acesso.
• authenticated quando é apresentado um token de acesso válido.
• <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 utilizador que também está incluída na afirmação do token de roles acesso.

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

Funções de sistema

As funções de sistema são funções incorporadas reconhecidas pelo Construtor de API de Dados. Uma função de sistema é automaticamente atribuída a um requerente, independentemente da associação à função do requerente indicada nos respetivos tokens de acesso. Existem duas funções de sistema: anonymous e authenticated.

Função de sistema anónimo

A anonymous função de sistema é atribuída a pedidos executados por utilizadores não autenticados. As entidades definidas pela configuração do runtime têm de incluir permissões para a função anonymous se o acesso não autenticado for desejado.

Exemplo

A seguinte configuração do runtime do construtor de API de Dados demonstra a configuração explícita da função anonymous de sistema para incluir o acesso de leitura à entidade Livro:

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

Quando uma aplicação cliente envia um pedido de acesso à entidade Livro em nome de um utilizador não autenticado, a aplicação não deve incluir o Authorization cabeçalho HTTP.

Função de sistema autenticada

A authenticated função de sistema é atribuída a pedidos executados por utilizadores autenticados.

Exemplo

A seguinte configuração do runtime do construtor de API de Dados demonstra a configuração explícita da função authenticated de sistema para incluir o acesso de leitura à entidade Livro:

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

Funções de utilizador

As funções de utilizador são funções não sistema atribuídas aos utilizadores no fornecedor de identidade que definiu na configuração de runtime. Para que o construtor de API de Dados avalie um pedido no contexto de uma função de utilizador, têm de ser cumpridos dois requisitos:

1. O token de acesso fornecido pela aplicação cliente tem de incluir afirmações de função que listam a associação à função de um utilizador.
2. A aplicação cliente tem de incluir o cabeçalho X-MS-API-ROLE HTTP com pedidos e definir o valor do cabeçalho como a função de utilizador pretendida.

Exemplo de avaliação de função

O exemplo seguinte demonstra os pedidos feitos à Book entidade que está configurada na configuração do runtime do construtor de API de Dados da seguinte forma:

"Book": {
    "source": "books",
    "permissions": [
        {
            "role": "anonymous",
            "actions": [ "read" ]
        },
        {
            "role": "authenticated",
            "actions": [ "read" ]
        },
        {
            "role": "author",
            "actions": [ "read" ]
        }
    ]
}

No Aplicações Web Estáticas, um utilizador é membro da função anónima por predefinição. Se o utilizador for autenticado, o utilizador é membro das anonymous funções e authenticated .

Quando uma aplicação cliente envia um pedido autenticado para o construtor de API de Dados implementado com Aplicações Web Estáticas conexões de banco de dados (Pré-visualização), a aplicação cliente fornece um token de acesso que Aplicações Web Estáticas transforma em JSON:

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

Uma vez que o Construtor de API de Dados avalia os pedidos no contexto de uma única função, avalia o pedido no contexto da função authenticated de sistema por predefinição.

Se o pedido da aplicação cliente também incluir o cabeçalho X-MS-API-ROLE HTTP com o valor author, o pedido é avaliado no contexto da função author . Um pedido 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 pedidos numa entidade com base na associação a funções?
• Que ações (criar, ler, atualizar, eliminar, executar) podem ser executadas por um utilizador?
• Que campos estão acessíveis para uma determinada ação?
• Que restrições adicionais existem nos resultados devolvidos por um pedido?

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

Proteger por predefinição

Por predefinição, uma entidade não tem permissões configuradas, o que significa que ninguém pode aceder à entidade. Além disso, o construtor de API de Dados ignora objetos de base de dados quando não são referenciados na configuração do runtime.

As permissões têm de ser explicitamente configuradas

Para permitir o acesso não autenticado a uma entidade, a anonymous função tem de ser explicitamente definida nas permissões da entidade. Por exemplo, as book permissões da entidade estão explicitamente definidas 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 numa entidade, suponha que, se não existirem permissões específicas para a authenticated função, são utilizadas as permissões definidas para a função anonymous . A book configuração apresentada anteriormente permite que qualquer utilizador anónimo ou autenticado realize operações de leitura na book entidade.

Quando as operações de leitura devem ser restritas apenas a utilizadores autenticados, deve ser definida a seguinte configuração de permissões, o que resulta na rejeição de pedidos não autenticados:

"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 utilizador podem ser definidas na configuração de permissões de uma entidade e todas as outras funções indefinidas, o sistema ou o utilizador definidos são automaticamente negados.

No exemplo seguinte, a função administrator de utilizador é a única função definida para a book entidade. Um utilizador tem de ser membro da função administrator 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 no âmbito de uma função. As ações podem ser especificadas individualmente ou com o atalho universal: * (asterisco). O atalho universal representa todas as ações suportadas para o tipo de entidade:

• Tabelas e Vistas: create, , read, updatedelete
• Procedimentos Armazenados: execute

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

Acesso a campos

Pode configurar os campos que devem estar acessíveis para uma ação. Por exemplo, pode definir os campos a incluir e excluir da ação read .

O exemplo seguinte impede que os utilizadores na função free-access realizem operações de leitura em Column3. As referências a Column3 pedidos GET (ponto final REST) ou consultas (ponto final do GraphQL) resultam num pedido rejeitado:

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

Segurança ao nível do item

As expressões de política de base de dados permitem que os resultados sejam ainda mais restritos. As políticas de base de dados traduzem expressões para predicados de consulta executados na base de dados. As expressões de política de base de dados são suportadas para as seguintes ações:

Para obter mais informações sobre as políticas de base de dados, veja a documentação do ficheiro de configuração .

Exemplo

Uma política de base de dados que restringe a ação read na função consumer para devolver apenas registos 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