Criar um script de reivindicações de token personalizadas

Para adicionar reivindicações personalizadas ao token de acesso, você precisa fornecer um script que retorne um objeto contendo essas reivindicações. O script deve ser escrito como uma função JavaScript que retorna um objeto com as reivindicações personalizadas.

1. Navegue para Console > Custom JWT.

2. Existem dois tipos diferentes de tokens de acesso para os quais você pode personalizar as reivindicações do token de acesso:

   • Token de acesso do usuário: O token de acesso emitido para usuários finais. Por exemplo, para aplicativos Web ou aplicativos móveis.
   • Token de acesso máquina para máquina: O token de acesso emitido para os serviços ou aplicativos. Por exemplo, para aplicativos máquina para máquina.

   Diferentes tipos de tokens de acesso podem ter diferentes contextos de carga útil do token. Você pode personalizar as reivindicações do token para cada tipo de token de acesso separadamente.

   Escolha qualquer tipo de token de acesso para o qual você deseja personalizar as reivindicações do token e clique no botão Adicionar reivindicações personalizadas para criar um novo script.

nota

O recurso de reivindicações de token personalizadas está disponível apenas para:

• Usuários OSS
• Locatários Dev
• Locatários pagos (incluindo locatários Pro e locatários Enterprise)

Implementar a função getCustomJwtClaims()

Na página de detalhes do Custom JWT, você pode encontrar o editor de scripts para escrever seu script de reivindicações de token personalizadas. O script deve ser uma função JavaScript que retorna um objeto de reivindicações personalizadas.

Passo 1: Editar o script

Use o editor de código no lado esquerdo para modificar o script. Um getCustomJwtClaims padrão com um valor de retorno de objeto vazio é fornecido para você começar. Você pode modificar a função para retornar um objeto de suas próprias reivindicações personalizadas.

const getCustomJwtClaims = async ({ token, context, environmentVariables }) => {
  return {};
};

Este editor usa o servidor de linguagem JavaScript para fornecer realce de sintaxe básico, conclusão de código e verificação de erros. O parâmetro de entrada é bem tipado e documentado no estilo jsDoc. Você pode usar o IntelliSense do editor para acessar corretamente as propriedades do objeto de entrada. Você pode encontrar as definições detalhadas dos parâmetros no lado direito da página.

nota

Esta função será exportada como um módulo. Certifique-se de manter o nome da função como getCustomJwtClaims para que o módulo possa exportar a função corretamente.

Passo 2: Parâmetros de entrada

A função getCustomJwtClaims recebe um objeto como parâmetro de entrada. O objeto de entrada contém as seguintes propriedades:

token

O objeto de carga útil do token. Este objeto contém reivindicações de token originais e metadados que você pode precisar acessar no script.

Você pode encontrar a definição de tipo detalhada do objeto de carga útil do token e do objeto de dados do usuário no lado direito da página. O IntelliSense do editor também ajudará você a acessar corretamente essas propriedades do objeto de entrada.

• Objeto de dados do token de acesso do usuário

  Propriedade	Descrição	Tipo
  jti	O ID único do JWT	string
  aud	O público do token	string
  scope	Os escopos do token	string
  clientId	O ID do cliente do token	string
  accountId	O ID do usuário do token	string
  expiresWithSession	Se o token expirará com a sessão	boolean
  grantId	O ID da concessão de autenticação atual do token	string
  gty	O tipo de concessão do token	string
  kind	O tipo de token	AccessToken

• Objeto de dados do token de acesso máquina para máquina

  Propriedade	Descrição	Tipo
  jti	O ID único do JWT	string
  aud	O público do token	string
  scope	Os escopos do token	string
  clientId	O ID do cliente do token	string
  kind	O tipo de token	ClientCredentials

context (Disponível apenas para token de acesso do usuário)

O objeto de contexto contém os dados do usuário e os dados da concessão relevantes para o processo de autorização atual.

• Objeto de dados do usuário Para o token de acesso do usuário, o Logto fornece um contexto de dados do usuário adicional para você acessar. O objeto de dados do usuário contém todos os dados do perfil do usuário e dados de associação à organização que você pode precisar para configurar as reivindicações personalizadas. Por favor, verifique Usuários e Organizações para mais detalhes.
• Objeto de dados da concessão Para o token de acesso do usuário concedido por troca de token de imitação, o Logto fornece um contexto de dados de concessão adicional para você acessar. O objeto de dados da concessão contém o contexto personalizado do token do sujeito. Por favor, verifique Imitação de usuário para mais detalhes.

environmentVariables

Use a seção Definir variáveis de ambiente à direita para configurar as variáveis de ambiente para seu script. Você pode usar essas variáveis para armazenar informações sensíveis ou dados de configuração que você não deseja codificar no script. Por exemplo, chaves de API, segredos ou URLs.

Todas as variáveis de ambiente que você definir aqui estarão disponíveis no script. Use o objeto environmentVariables no parâmetro de entrada para acessar essas variáveis.

api

O objeto api fornece um conjunto de funções utilitárias que você pode usar em seu script para controle de acesso adicional sobre o processo de emissão de tokens. O objeto api contém as seguintes funções:

api.denyAccess(message?: string): void

A função api.denyAccess() permite que você negue o processo de emissão de tokens com uma mensagem personalizada. Você pode usar essa função para impor validações de acesso adicionais sobre o processo de emissão de tokens.

Passo 3: Buscar dados externos

Você pode usar a função fetch embutida do node para buscar dados externos em seu script. A função fetch é uma função baseada em promessa que permite fazer solicitações HTTP para APIs externas.

const getCustomJwtClaims = async ({ environmentVariables }) => {
  const response = await fetch('https://api.example.com/data', {
    headers: {
      Authorization: `Bearer ${environmentVariables.API_KEY}`,
    },
  });

  const data = await response.json();

  return {
    data,
  };
};

nota

Esteja ciente de que qualquer busca de dados externos pode introduzir latência no processo de emissão de tokens. Certifique-se de que a API externa seja confiável e rápida o suficiente para atender aos seus requisitos.

Além disso:

• Lide com erros e tempo limite adequadamente em seu script para evitar que o processo de emissão de tokens seja bloqueado.
• Use cabeçalhos de autorização adequados para proteger sua API externa contra acesso não autorizado.

Passo 4: Testar o script

Certifique-se de testar seu script antes de salvá-lo. Clique na aba Testar contexto no lado direito da página para modificar a carga útil do token simulado e o contexto de dados do usuário para teste.

Clique em Executar teste no canto superior direito do editor para executar o script com os dados simulados. A saída do script será exibida na gaveta Resultado do Teste.

nota

O resultado do teste é a saída da função getCustomJwtClaims com os dados simulados que você definiu ("reivindicações de token extras" obtidas após completar o passo 3 no diagrama de sequência). A carga útil real do token e o contexto de dados do usuário serão diferentes quando o script for executado no processo de emissão de tokens.

Clique no botão Criar para salvar o script. O script de reivindicações de token personalizadas será salvo e aplicado ao processo de emissão de tokens de acesso.