Compartilhar via

Configurar a autenticação do Simulador para testes locais

O provedor de autenticação do Simulador permite testar permissões baseadas em função localmente sem configurar um provedor de identidade. Use-o durante o desenvolvimento para verificar se as regras de permissão funcionam corretamente antes de implantar em produção.

Escolher um provedor de autenticação local

Durante o desenvolvimento, você pode testar a autenticação e a autorização sem configurar um provedor de identidade de produção.

Fornecedor Mais adequado para Anotações
Simulador Teste rápido de permissão Somente para desenvolvimento. Trata cada solicitação como autenticada. Padrões para a função Authenticated; substituir por X-MS-API-ROLE.
AppService Teste controlado por declarações Simule o EasyAuth localmente enviando X-MS-CLIENT-PRINCIPAL com declarações personalizadas. Para obter detalhes, consulte Configurar a autenticação do Serviço de Aplicativo.

Fluxo de autenticação

O provedor simulador trata todas as solicitações como autenticadas, permitindo que você se concentre em testar regras de autorização:

Ilustração do fluxo de autenticação do Simulador mostrando como as solicitações são tratadas automaticamente como autenticadas.

Phase O que acontece
A solicitação chega Desenvolvedor envia solicitação HTTP ao DAB
Atribuição de função O DAB atribui Authenticated (padrão) ou a função do cabeçalho X-MS-API-ROLE
Verificação de permissão O DAB avalia a solicitação em relação às permissões da entidade para essa função
Execução da consulta Se permitido, o DAB consulta o banco de dados e retorna resultados

Importante

O provedor do Simulador destina-se apenas ao desenvolvimento. Nunca use-o em produção; pois ignora toda a autenticação real.

Pré-requisitos

  • 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

Configurações Value
Fornecedor Simulator
Modo de host development (obrigatório)
Função padrão Authenticated (injetado automaticamente)
Cabeçalho de sobreposição de permissões X-MS-API-ROLE
Token necessário Não
Suporte a reivindicações Limitado (somente funções Anonymous/Authenticated do sistema; sem declarações arbitrárias)

Etapa 1: Configurar o provedor do Simulador

Defina o provedor de autenticação como Simulador e verifique se o modo de desenvolvimento está habilitado.

CLI

# Enable development mode
dab configure \
  --runtime.host.mode development

# Set the Simulator provider
dab configure \
  --runtime.host.authentication.provider Simulator

Configuração resultante

{
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  }
}

Observação

O provedor do Simulador só funciona quando mode é definido como development. No modo de produção, o DAB rejeita o provedor simulador e falha ao iniciar.

Etapa 2: Configurar permissões de entidade

Defina permissões para as funções que você deseja testar. Você pode testar funções do sistema (Anonymous, Authenticated) e funções personalizadas.

Exemplo: Várias funções

# Allow anonymous read access
dab update Book \
  --permissions "Anonymous:read"

# Allow authenticated users full read access
dab update Book \
  --permissions "Authenticated:read"

# Allow authors to create and update
dab update Book \
  --permissions "author:create,read,update"

# Allow admins full access
dab update Book \
  --permissions "admin:*"

Configuração resultante

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Etapa 3: Testar funções diferentes

Inicie o construtor de API de Dados e envie solicitações para testar cada função.

dab start

Testar como autenticado (padrão)

Sem cabeçalhos especiais, as solicitações são avaliadas como a Authenticated função:

curl -X GET "http://localhost:5000/api/Book"

Testar como anônimo

Use o X-MS-API-ROLE cabeçalho para testar como Anonymous:

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous"

Testar como uma função personalizada

Use o X-MS-API-ROLE cabeçalho para testar qualquer função personalizada:

curl -X GET "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: author"

Observação

Com o Simulador, o teste de função customizada funciona porque o DAB avalia permissões com base no valor do cabeçalho X-MS-API-ROLE. As funções do sistema (Anonymous, Authenticated) estão sempre disponíveis. Se uma solicitação de função personalizada retornar 403, verifique se o nome da função corresponde exatamente às suas permissões de entidade.

Testar uma ação que deve ser recusada

Tente uma ação para a qual a função não tenha permissão para:

# This should fail—Anonymous can only read
curl -X POST "http://localhost:5000/api/Book" \
  -H "X-MS-API-ROLE: Anonymous" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Book", "author": "Test"}'

Resposta esperada: 403 Forbidden

Cenários de teste

Use o Simulador para testar esses cenários comuns:

Scenario Como testar
Acesso anônimo Defina X-MS-API-ROLE: Anonymous
Acesso autenticado Omitir cabeçalhos (padrão) ou definir X-MS-API-ROLE: Authenticated
Acesso a função personalizada Defina X-MS-API-ROLE: <role-name>
Ação negada Solicitar uma ação para a qual a função não tem permissão
Restrições de campo Configurar permissões no nível do campo e verificar campos de resposta
Função ausente Definir X-MS-API-ROLE: nonexistent para testar o tratamento de erros

Limitações

O provedor do Simulador tem estas limitações:

Limitation Solução Alternativa
Nenhuma reivindicação personalizada Usar o provedor do AppService com o cabeçalho X-MS-CLIENT-PRINCIPAL
Nenhuma política de banco de dados com reivindicações Testar políticas usando o provedor AppService
Nenhuma validação de token Alterne para Entra ou provedor personalizado para produção
Somente modo de desenvolvimento Usar um provedor real na produção

Dica

Se você precisar testar políticas de banco de dados que usam declarações (como @claims.userId), use o provedor AppService . Ele permite que você forneça declarações personalizadas por meio do X-MS-CLIENT-PRINCIPAL cabeçalho.

Transição para produção

Quando estiver pronto para implantar, substitua o provedor Simulator por um provedor de produção.

  1. Alterar mode de development para production
  2. Altere provider de Simulator para o provedor escolhido (EntraID/AzureAD, AppService ou Custom)
  3. Definir as configurações de JWT necessárias (audiência, emissor)
{
  "runtime": {
    "host": {
      "mode": "production",
      "authentication": {
        "provider": "EntraID",
        "jwt": {
          "audience": "api://<your-app-id>",
          "issuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
        }
      }
    }
  }
}

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": "Server=localhost;Database=Library;Trusted_Connection=true;TrustServerCertificate=true;"
  },
  "runtime": {
    "host": {
      "mode": "development",
      "authentication": {
        "provider": "Simulator"
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "Anonymous",
          "actions": ["read"]
        },
        {
          "role": "Authenticated",
          "actions": ["read"]
        },
        {
          "role": "author",
          "actions": ["create", "read", "update"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Conteúdo relacionado

  • Last updated on