Configurar a autenticação do Serviço de Aplicativo (EasyAuth)

O Serviço de Aplicativo do Azure fornece autenticação interna (geralmente chamada de "EasyAuth") que manipula a entrada do usuário antes que as solicitações cheguem ao seu aplicativo. O Construtor de API de Dados pode ler as informações de identidade que o Serviço de Aplicativo injeta, habilitando a autenticação sem gerenciar tokens diretamente.

Fluxo de autenticação

Quando o Construtor de API de Dados é executado por trás do Serviço de Aplicativo do Azure com a autenticação habilitada, o Serviço de Aplicativo manipula o fluxo OAuth e passa informações de identidade por meio de cabeçalhos HTTP:

Pré-requisitos

• Uma assinatura de Azure
• Serviço de Aplicativo do Azure ou Azure Functions (na infraestrutura do Serviço de Aplicativo)
• CLI do Construtor de API de Dados instalada (guia de instalação)
• um objeto existente dab-config.json com pelo menos uma entidade

Referência rápida

Etapa 1: Habilitar a autenticação do Serviço de Aplicativo

Configurar a autenticação no Serviço de Aplicativo do Azure:

1. No portal do Azure, navegue até o Serviço de Aplicativo.

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

3. Selecione Adicionar provedor de identidade.

4. Escolha a Microsoft (ou outro provedor com suporte).

5. Defina as configurações:

   • Tipo de registro de aplicativo: Criar novo ou selecionar existente
   • Tipos de conta com suporte: escolha com base em seu cenário
   • Restringir o acesso: exigir autenticação

6. Selecione Adicionar.

Etapa 2: Configurar o construtor de API de Dados

Defina o provedor de autenticação como AppService:

CLI

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

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

Configuração resultante

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

Etapa 3: Configurar permissões de entidade

Defina permissões para funções. O Data API builder avalia os papéis por meio de ClaimsPrincipal.IsInRole(), que verifica as declarações analisadas no cabeçalho X-MS-CLIENT-PRINCIPAL. Inclua declarações de função na claims matriz com o tipo de declaração de função apropriado.

Configuração de exemplo

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

Etapa 4: Testar localmente com X-MS-CLIENT-PRINCIPAL

Você pode testar a autenticação do Serviço de Aplicativo localmente fornecendo manualmente o X-MS-CLIENT-PRINCIPAL cabeçalho. Essa abordagem simula o que o EasyAuth encaminha para seu aplicativo e permite que você teste a função e o comportamento controlado por declarações sem implantar no Azure.

Criar um principal de cliente

O X-MS-CLIENT-PRINCIPAL cabeçalho contém um objeto JSON codificado em Base64. O Construtor de API de Dados 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 principal

Codificar o JSON como Base64. Você 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

Enviar uma solicitação 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 analisa as seguintes propriedades do principal do cliente:

Usando declarações em políticas de banco de dados

Com o provedor AppService, você pode usar declarações em políticas de banco de dados. Essa funcionalidade permite a segurança em nível de linha com base na identidade do usuário.

Exemplo: Filtrar por ID de objeto de usuário

Este exemplo usa a oid declaração (identificador de objeto), que o ID do Microsoft Entra inclui em tokens:

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

Referências de declaração disponíveis

As referências de reivindicação usam a string de tipo de reivindicação exata do array claims.

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

Solicitações anônimas

Quando o Serviço de Aplicativo permite solicitações não autenticadas ou ao testar localmente sem o cabeçalho, o middleware de autenticação do API Data Builder configura o cabeçalho X-MS-CLIENT-PRINCIPAL para X-MS-API-ROLE automaticamente. As solicitações são então avaliadas usando a anonymous função:

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

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

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

Solução de problemas

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 em nível de linha com contexto de sessão
• Configurar a autenticação da ID do Microsoft Entra
• Configurar a autenticação do Simulador para teste