Configurar autenticação de App Service (EasyAuth)

O Serviço de Aplicações do Azure fornece autenticação incorporada (frequentemente chamada de "EasyAuth") que gere o início de sessão do utilizador antes de os pedidos chegarem à sua aplicação. O Data API Builder pode ler a informação de identidade que o App Service injeta, permitindo a autenticação sem gerir os tokens diretamente.

Fluxo de autenticação

Quando o Data API Builder corre atrás do Serviço de Aplicações do Azure com a autenticação ativada, o App Service gere o fluxo OAuth e passa a informação de identidade através de cabeçalhos HTTP:

Pré-requisitos

• Uma assinatura do Azure
• Serviço de Aplicações do Azure ou Funções do Azure (na infraestrutura App Service)
• CLI do construtor de APIs de dados instalado (guia de instalação)
• Um existente dab-config.json com no mínimo uma entidade

Referência rápida

Passo 1: Ativar a autenticação do App Service

Configurar autenticação no Serviço de Aplicações do Azure:

1. No portal Azure, navegue até ao seu App Service.

2. Selecione Configurações>Autenticação.

3. Selecione Adicionar provedor de identidade.

4. Escolha a Microsoft (ou outro fornecedor suportado).

5. Configurar as configurações:

   • Tipo de registo da aplicação: Criar um novo ou selecionar o existente
   • Tipos de conta suportados: Escolha com base no seu cenário
   • Restringir acesso: Exigir autenticação

6. Selecione Adicionar.

Passo 2: Configurar Data API Builder

Defina o fornecedor de autenticação para AppService:

CLI

dab configure \
  --runtime.host.authentication.provider AppService

dab configure ^
  --runtime.host.authentication.provider AppService

Configuração resultante

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  }
}

Passo 3: Configurar permissões de entidade

Definir permissões para funções. O Data API Builder avalia as funções via ClaimsPrincipal.IsInRole(), que verifica as declarações extraídas do cabeçalho X-MS-CLIENT-PRINCIPAL. Inclua declarações de função no array claims com o tipo de declaração de função adequado.

Exemplo de configuração

# Allow authenticated users to read
dab update Book \
  --permissions "authenticated:read"

# Allow editors to create and update
dab update Book \
  --permissions "editor:create,read,update"

REM Allow authenticated users to read
dab update Book ^
  --permissions "authenticated:read"

REM Allow editors to create and update
dab update Book ^
  --permissions "editor:create,read,update"

Configuração resultante

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Passo 4: Teste localmente com X-MS-CLIENT-PRINCIPAL

Pode testar a autenticação do App Service localmente, fornecendo manualmente o X-MS-CLIENT-PRINCIPAL cabeçalho. Esta abordagem simula o que o EasyAuth encaminha para a sua aplicação e permite-lhe testar o comportamento baseado em funções e declarações, sem necessidade de implementação no Azure.

Crie um cliente principal

O X-MS-CLIENT-PRINCIPAL cabeçalho contém um objeto JSON codificado em Base64. O Data API builder analisa as seguintes propriedades:

{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "Alice Smith" },
    { "typ": "email", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" },
    { "typ": "http://schemas.microsoft.com/identity/claims/objectidentifier", "val": "abc-123-def" }
  ]
}

Codificar o elemento principal

Codifica o JSON como Base64. Pode usar qualquer ferramenta:

PowerShell::

$json = @'
{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}
'@
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($json))

Bash:

echo '{
  "auth_typ": "aad",
  "name_typ": "name",
  "role_typ": "roles",
  "claims": [
    { "typ": "name", "val": "alice@contoso.com" },
    { "typ": "roles", "val": "authenticated" },
    { "typ": "roles", "val": "editor" }
  ]
}' | base64

Envie um pedido com o cabeçalho

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-CLIENT-PRINCIPAL: eyJpZGVudGl0eVByb3ZpZGVyIjoiYWFkIiwidXNlcklkIjoidXNlci0xMjM0NSIsInVzZXJEZXRhaWxzIjoiYWxpY2VAY29udG9zby5jb20iLCJ1c2VyUm9sZXMiOlsiYXV0aGVudGljYXRlZCIsImVkaXRvciJdfQ==" \
  -H "X-MS-API-ROLE: editor"

Estrutura X-MS-CLIENT-PRINCIPAL

O Data API builder analisa as seguintes propriedades do principal cliente:

Utilização de declarações em políticas de base de dados

Com o fornecedor da AppService, pode usar declarações nas políticas da base de dados. Esta capacidade permite segurança ao nível das linhas com base na identidade do utilizador.

Exemplo: Filtrar por ID de objeto de utilizador

Este exemplo utiliza a afirmação oid (identificador de objeto), que o Microsoft Entra ID inclui nos tokens:

{
  "entities": {
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Referências disponíveis para reivindicações

As referências de reivindicações usam a cadeia exata de tipo de reivindicação do claims array:

Por exemplo, se o seu principal incluir { "typ": "email", "val": "alice@contoso.com" }, utilize @claims.email na sua política. O tipo de reclamação deve corresponder exatamente.

Pedidos anónimos

Quando o App Service permite pedidos não autenticados, ou ao testar localmente sem o cabeçalho X-MS-CLIENT-PRINCIPAL, o middleware de autenticação do Data API Builder define o cabeçalho X-MS-API-ROLE para anonymous automaticamente. Os pedidos são avaliados utilizando a função anonymous.

# No principal header = anonymous role (X-MS-API-ROLE set automatically)
curl -X GET "http://localhost:5000/api/Book"

Para acesso anónimo a funcionalidades, a sua entidade deve ter permissões para a anonymous função:

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

Troubleshooting

Exemplo de configuração completa

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "connection-string": "@env('SQL_CONNECTION_STRING')"
  },
  "runtime": {
    "host": {
      "authentication": {
        "provider": "AppService"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["read"]
        },
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update", "delete"]
        }
      ]
    },
    "Order": {
      "source": "dbo.Orders",
      "permissions": [
        {
          "role": "authenticated",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "@claims.oid eq @item.customerId"
              }
            }
          ]
        }
      ]
    }
  }
}

Conteúdo relacionado

• Visão geral da autorização
• Segurança a nível de linha com contexto de sessão
• Configurar autenticação do ID Microsoft Entra
• Configurar a autenticação do simulador para testes