Criar um script de reivindicações personalizadas de token

Para adicionar reivindicações personalizadas ao token de acesso (Access token), 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.

Navegue até Console > JWT personalizado.
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. Ex.: para aplicativos Web ou aplicativos móveis.
- Token de acesso máquina para máquina: O token de acesso emitido para serviços ou aplicativos. Ex.: para aplicativos máquina para máquina.
Diferentes tipos de tokens de acesso podem ter diferentes contextos de payload 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 que 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 personalizadas de token está disponível apenas para:

Usuários do Logto OSS
Locatários do Logto Cloud com ambiente de desenvolvimento
Locatários pagos do Logto Cloud com ambiente de produção (incluindo locatários Pro e locatários Enterprise)

Implementar a função `getCustomJwtClaims()`

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

Página de detalhes de reivindicações personalizadas de token

Passo 1: Edite 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 com suas próprias reivindicações personalizadas.

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

Este editor utiliza o servidor de linguagem JavaScript para fornecer realce de sintaxe básico, autocompletar 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ê 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 payload do token. Este objeto contém as reivindicações originais do token e metadados que você pode precisar acessar no script.

Você pode encontrar a definição de tipo detalhada do objeto payload 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 irá 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 do 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 do token ClientCredentials

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

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

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

Objeto de dados de interação do usuário Para um determinado token de acesso do usuário, pode haver situações em que você precise acessar os detalhes de interação do usuário para a sessão de autorização atual. Por exemplo, você pode precisar recuperar a identidade SSO corporativa do usuário usada para login. Este objeto de dados de interação do usuário contém os dados de interação mais recentes enviados pelo usuário, incluindo:

Propriedade	Descrição	Tipo
`interactionEvent`	O evento de interação da interação atual do usuário	`SignIn` ou `Register`
`userId`	O id do usuário da interação atual	`string`
`verificationRecords`	Uma lista de registros de verificação enviados pelo usuário para identificar e verificar sua identidade durante as interações.	`VerificationRecord[]`

Tipo de registro de verificação:

// VerificationType.Password
{
  id: string;
  type: 'Password';
  identifier: {
    type: 'username' | 'email' | 'phone' | 'userId';
    value: string;
  }
  verified: boolean;
}

// VerificationType.EmailVerificationCode
{
  id: string;
  templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
  verified: boolean;
  type: 'EmailVerificationCode';
  identifier: {
    type: 'email';
    value: string;
  }
}

// VerificationType.PhoneVerificationCode
{
  id: string;
  templateType: 'SignIn' | 'Register' | 'ForgotPassword' | 'Generic';
  verified: boolean;
  type: 'PhoneVerificationCode';
  identifier: {
    type: 'phone';
    value: string;
  }
}

// VerificationType.Social
{
  id: string;
  type: 'Social';
  connectorId: string;
  socialUserInfo?: {
    id: string;
    email?: string | undefined;
    phone?: string | undefined;
    name?: string | undefined;
    avatar?: string | undefined;
    rawData?: Record<string, unknown> | undefined;
  } | undefined;
}

// VerificationType.EnterpriseSso
{
  id: string;
  type: 'EnterpriseSso';
  connectorId: string;
  enterpriseUserInfo?: {
    id: string;
    email?: string | undefined;
    phone?: string | undefined;
    name?: string | undefined;
    avatar?: string | undefined;
    [key: string]?: unknown;
  } | undefined;
  issuer?: string | undefined;
}

// VerificationType.Totp (MFA)
{
  id: string;
  type: 'Totp';
  userId: string;
  verified: boolean;
}

// VerificationType.WebAuthn (MFA)
{
  id: string;
  type: 'WebAuthn';
  userId: string;
  verified: boolean;
}

// VerificationType.BackupCode (MFA)
{
  id: string;
  type: "BackupCode";
  userId: string;
  code?: string | undefined;
}

// VerificationType.OneTimeToken
{
  id: string;
  type: "OneTimeToken";
  verified: boolean;
  identifier: {
    type: "email";
    value: string;
  };
  oneTimeTokenContext?: {
    jitOrganizationIds?: string[] | undefined;
  } | undefined;
}

nota:

Pode haver vários registros de verificação no objeto de dados de interação do usuário, especialmente quando o usuário passou por vários processos de login ou registro.

Ex.: o usuário fez login usando um registro de verificação Social, depois vinculou um novo endereço de e-mail através de um registro de verificação EmailVerificationCode e, em seguida, verificou o status MFA com um registro de verificação Totp. Nesse caso, você pode precisar tratar todos os registros de verificação adequadamente em seu script.

Cada tipo de registro de verificação estará presente apenas uma vez no objeto de dados de interação do usuário.

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 não deseja codificar diretamente no script. Ex.: 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 do token. O objeto api contém as seguintes funções:

api.denyAccess(message?: string): void

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

Passo 3: Buscar dados externos

Você pode usar a função nativa do node fetch para buscar dados externos em seu script. A função fetch é baseada em promessas e permite fazer requisiçõ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:

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

Além disso:

Trate erros e timeout adequadamente em seu script para evitar que o processo de emissão do token seja bloqueado.
Use cabeçalhos de autorização apropriados para proteger sua API externa contra acessos não autorizados.

Passo 4: Teste o script

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

Clique em Executar teste no canto superior direito do editor para rodar 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 extras do token" obtidas após concluir o passo 3 no diagrama de sequência). O payload real do token e o contexto de dados do usuário serão diferentes quando o script for executado no processo de emissão do token.

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

Implementar a função getCustomJwtClaims()​

Passo 1: Edite o script​

Passo 2: Parâmetros de entrada​

token​

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

environmentVariables​

api​

Passo 3: Buscar dados externos​

Passo 4: Teste o script​

Implementar a função `getCustomJwtClaims()`

Passo 1: Edite o script

Passo 2: Parâmetros de entrada

token

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

environmentVariables

api

Passo 3: Buscar dados externos

Passo 4: Teste o script