Compartilhar via

Configurar a autenticação JWT personalizada (Okta, Auth0)

O Construtor de API de Dados dá suporte a provedores de identidade de terceiros por meio do provedor de autenticação personalizado. Use essa abordagem quando sua organização usar Okta, Auth0 ou outro provedor de identidade compatível com o OAuth 2.0/OpenID Connect.

Fluxo de autenticação

Com um provedor de identidade personalizado, seu aplicativo cliente manipula a autenticação do usuário e envia o token de acesso para o construtor de API de Dados:

Ilustração do fluxo de autenticação JWT personalizado com um provedor de identidade de terceiros.

Phase O que acontece
Autenticação de usuário O usuário entra por meio do provedor de identidade (Okta, Auth0, etc.)
Aquisição de token O aplicativo cliente recebe um token de acesso do IdP
Chamada à API O cliente envia o token para o Authorization DAB no cabeçalho
Validação O DAB valida o JWT (emissor, audiência, assinatura)
Autorização O DAB extrai funções e avalia permissões

Pré-requisitos

  • Uma conta com seu provedor de identidade (Okta, Auth0, etc.)
  • Um aplicativo registrado em seu provedor de identidade
  • 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 Custom
Necessário para validação iss, aud, expassinatura válida
Necessário para autorização roles declaração que contém a função selecionada
Cabeçalho de token Authorization: Bearer <token>
Tipo de declaração de função roles (corrigido, não configurável)
Cabeçalho de seleção de função X-MS-API-ROLE

Etapa 1: Configurar seu provedor de identidade

As etapas exatas dependem do seu provedor. Aqui estão os principais valores de que você precisa:

Valores a serem coletados

Value Onde encontrá-lo Usado para
URL do emissor Documentação do provedor ou endpoint de metadados OAuth DAB jwt.issuer (usado como Autoridade JWT)
Público ID do cliente do aplicativo ou um identificador de API personalizado DAB jwt.audience

Observação

O DAB usa a configuração definida em jwt.issuer como a Autoridade JWT. As chaves de assinatura são descobertas automaticamente por meio de metadados padrão do OpenID Connect (normalmente <issuer>/.well-known/openid-configuration).

Exemplo de Okta

  1. Entre no Console de Administração do Okta.
  2. Navegue até Aplicativos>Aplicativos.
  3. Crie ou selecione um aplicativo.
  4. Observe a ID do cliente (use como público-alvo).
  5. Normalmente, o emissor é https://<your-domain>.okta.com.

Exemplo de Auth0

  1. Faça login no Painel de Controle do Auth0.
  2. Navegue até Aplicativos>APIs.
  3. Crie ou selecione uma API.
  4. Anote o Identificador (use como audiência).
  5. Seu emissor é https://<your-tenant>.auth0.com/.

Importante

O construtor de API de dados usa um tipo de roles declaração fixa para autorização baseada em função. Esse valor não pode ser configurado. Se o provedor de identidade emitir funções em uma declaração diferente (como groups ou permissions), você deverá configurar seu provedor para também emitir uma declaração roles ou usar uma ação realizada pós-login para copiar valores em uma declaração roles.

Etapa 2: Configurar o construtor de API de Dados

Defina o provedor de autenticação como Custom e configure as configurações do JWT:

CLI

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

# Set the expected audience
dab configure \
  --runtime.host.authentication.jwt.audience "<your-api-identifier>"

# Set the expected issuer
dab configure \
  --runtime.host.authentication.jwt.issuer "https://<your-issuer>/"

Configuração resultante

{
  "runtime": {
    "host": {
      "authentication": {
        "provider": "Custom",
        "jwt": {
          "audience": "<your-api-identifier>",
          "issuer": "https://<your-issuer>/"
        }
      }
    }
  }
}

Etapa 3: Configurar permissões de entidade

Defina permissões para as funções que seu provedor de identidade atribui:

CLI

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

# Allow users with 'admin' role full access
dab update Book \
  --permissions "admin:*"

Configuração resultante

{
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Etapa 4: Configurar funções em seu provedor de identidade

O DAB espera funções em uma roles declaração. Configure seu provedor de identidade para incluir essa declaração.

Okta: Adicionar grupos como funções

  1. No Console de Administração do Okta, acesse aAPI>.
  2. Selecione o servidor de autorização.
  3. Vá para a guia Declarações .
  4. Adicione uma declaração:
    • Nome: roles
    • Incluir no tipo de token: Token de Acesso
    • Tipo de valor: Grupos
    • Filtro: selecione os grupos a serem incluídos

Auth0: Adicionar funções com uma ação

  1. No Painel do Auth0, vá para Ações>Biblioteca.
  2. Criar uma nova Ação (gatilho pós-logon).
  3. Adicione código para incluir funções:
exports.onExecutePostLogin = async (event, api) => {
  const roles = event.authorization?.roles || [];
  if (roles.length > 0) {
    api.accessToken.setCustomClaim('roles', roles);
  }
};
  1. Implante a ação e adicione-a ao fluxo de logon.

Dica

Para obter diretrizes detalhadas sobre como configurar declarações JWT com o Okta, consulte Implementando declarações JWT avançadas com o SDK da Okta.

Etapa 5: Testar a configuração

  1. Iniciar o construtor de API de Dados:

    dab start

  2. Adquira um token do seu provedor de identidade. Use o SDK do provedor ou uma ferramenta como o Postman.

  3. Inspecione o token em jwt.io para verificar:

    • A aud declaração corresponde ao público configurado
    • A iss declaração corresponde ao emissor que você configurou
    • A roles declaração contém os valores esperados

  4. Acesse a API:

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>"

  5. Para usar uma função personalizada, inclua o X-MS-API-ROLE cabeçalho:

    curl -X GET "http://localhost:5000/api/Book" \
  -H "Authorization: Bearer <your-token>" \
  -H "X-MS-API-ROLE: admin"

Detalhes de validação do JWT

O construtor de API de Dados valida estes aspectos do JWT:

Verificação Description
Assinatura Validado usando chaves de assinatura descobertas por meio da autoridade configurada jwt.issuer (metadados do OpenID Connect/JWKS)
Emissor Deve corresponder exatamente à jwt.issuer configuração
Público Deve corresponder exatamente à jwt.audience configuração
Término O token não deve estar expirado (exp declaração)
Não antes O token deve ser válido (nbf claim, se presente)

Resolução de problemas

Sintoma Causa possível Solução
401 Unauthorized Incompatibilidade do emissor Verifique se a iss reivindicação corresponde exatamente (incluindo a barra final)
401 Unauthorized Desalinhamento de público Verifique se a declaração aud corresponde ao valor configurado
401 Unauthorized Token expirado Adquirir um token novo
401 Unauthorized Metadados indisponíveis Garantir que o DAB possa alcançar <issuer>/.well-known/openid-configuration
403 Forbidden Função não presente no token Adicionar a função à configuração do IdP
403 Forbidden Declaração de funções ausente Configurar seu IdP para incluir uma roles afirmação
403 Forbidden Nome de declaração incorreto O DAB usa o tipo roles de declaração (fixo, não configurável)

Importante

Atualmente, o DAB usa o tipo roles de declaração para todas as verificações de função. Esse valor é codificado e não pode ser alterado para groups, permissionsou outros nomes de declaração. Configure seu provedor de identidade para emitir funções em uma declaração chamada roles.

Formatos comuns do emissor

Fornecedor Formato do emissor
Okta https://<domain>.okta.com ou https://<domain>.okta.com/oauth2/default
Auth0 https://<tenant>.auth0.com/ (observe a barra à direita)
Azure AD B2C https://<tenant>.b2clogin.com/<tenant-id>/v2.0/
Keycloak https://<host>/realms/<realm>

Exemplo de configuração completa

Configuração do Okta

{
  "$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": "Custom",
        "jwt": {
          "audience": "0oa1234567890abcdef",
          "issuer": "https://dev-12345.okta.com"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "editor",
          "actions": ["create", "read", "update"]
        }
      ]
    }
  }
}

Configuração do Auth0

{
  "$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": "Custom",
        "jwt": {
          "audience": "https://my-api.example.com",
          "issuer": "https://my-tenant.auth0.com/"
        }
      }
    }
  },
  "entities": {
    "Book": {
      "source": "dbo.Books",
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["read"]
        },
        {
          "role": "admin",
          "actions": ["*"]
        }
      ]
    }
  }
}

Conteúdo relacionado

  • Last updated on