Adicionar claims personalizadas para tokens de acesso JWT com Logto para reforçar a tua autorização

Em artigos anteriores, mencionámos que mais e mais sistemas estão a usar tokens de acesso no formato JWT para autenticação de usuários e controlo de acesso. Uma das razões importantes para isso é que o JWT pode conter algumas informações úteis, como papéis e permissões de usuário. Estas informações podem ajudar-nos a passar informações de identidade do usuário entre o servidor e o cliente, alcançando assim a autenticação de usuários e controlo de acesso.

Geralmente, as informações contidas no JWT são determinadas pelo servidor de autenticação. De acordo com o protocolo OAuth 2.0, o JWT costuma conter campos como sub (assunto), aud (audiência) e exp (tempo de expiração), que são frequentemente referidos como claims. Estes claims podem ajudar a verificar a validade do token de acesso.

No entanto, há inúmeros cenários onde o JWT é utilizado para verificação, e as claims comuns de JWT podem frequentemente não satisfazer as necessidades do usuário. As pessoas costumam pensar que, como o JWT pode conter algumas informações, poderíamos adicionar algumas informações nele para facilitar a autorização?

A resposta é SIM, podemos adicionar claims personalizadas ao JWT, como o escopo e o nível de subscrição do usuário atual. Dessa forma, podemos passar informações de identidade do usuário entre o cliente e o servidor (aqui refere-se ao servidor que fornece vários serviços diferentes, também chamado de fornecedor de serviços), para alcançar a autenticação do usuário e o controlo de acesso.

Para claims padrão de JWT, por favor, consulta RFC7519. O Logto, como uma solução de identidade que suporta tanto autenticação como autorização, estendeu as claims de recurso e escopo com base nisso para suportar RBAC padrão. Embora a implementação do RBAC do Logto seja padrão, ela não é simples e flexível o suficiente para se adequar a todos os casos de uso.

Com base nisso, o Logto lançou um novo recurso de personalização de claims JWT, que permite aos usuários personalizarem claims adicionais de JWT, tornando a autenticação de usuários e o controlo de acesso mais flexíveis.

Como funciona a personalização de JWT Claims no Logto?#

Podes aceder à página de listagem de JWT personalizada clicando no botão "JWT claims" na barra lateral.

Vamos começar adicionando claims personalizadas para os usuários finais.

No editor à esquerda, podes personalizar a tua função getCustomJwtClaims. Este método tem três parâmetros de entrada: token, data e envVariables.

• token é o payload bruto do token de acesso obtido com base nas credenciais do usuário final atual e na configuração do teu sistema, e as informações do usuário relacionadas com acesso no Logto
• data é toda a informação sobre o usuário no Logto, incluindo todos os papéis do usuário, identidades de login social, identidades de SSO, associações a organizações, etc.
• envVariables são as variáveis de ambiente que configuraste no Logto para o cenário de uso do token de acesso do usuário final, como chave(s) de API dos APIs externos necessários, etc.

Os cartões à direita podem ser expandidos para mostrar a introdução dos parâmetros correspondentes, e também podes definir as variáveis de ambiente para o cenário atual aqui.

Depois de leres as introduções de todos os cartões à direita, podes mudar para o modo de teste, onde podes editar os dados de teste e usar os dados de teste editados para verificar se o comportamento do script que escreveste no editor de código à esquerda corresponde às tuas expectativas.

Este é um diagrama de sequência que mostra o processo de execução da função getCustomJwtClaims quando um usuário final inicia um pedido de autenticação para o Logto e eventualmente obtém o token de acesso no formato JWT retornado pelo Logto.

Se a funcionalidade de JWT Personalizado não estiver ativada, a etapa 3 no diagrama será ignorada e a etapa 4 será executada logo após o término da etapa 2. Neste ponto, o Logto assumirá que o valor retornado da getCustomJwtClaims é um objeto vazio, e então continuará a passar pelos passos subsequentes.

Reforça a tua autorização com claims JWT personalizadas: um exemplo prático#

Na seção anterior, introduzimos o princípio de funcionamento do JWT personalizado do Logto. Nesta parte, vamos mostrar como usar claims personalizadas JWT do Logto para melhorar a flexibilidade da autorização e o desempenho do fornecedor de serviços através de um exemplo real.

Configuração do cenário#

A equipa do John desenvolveu um app Assistente de IA que permite aos usuários conversarem com robôs de IA para obter vários serviços.

Os serviços do robô de IA são divididos em serviços gratuitos e pagos. Os serviços gratuitos incluem recomendações de tarifas aéreas especiais, enquanto os serviços pagos incluem previsões de ações.

O app Assistente de IA usa o Logto para gerir todos os usuários, que são divididos em três tipos: usuários gratuitos, usuários pré-pagos e usuários premium. Usuários gratuitos podem apenas usar serviços gratuitos, usuários pré-pagos podem usar todos os serviços (cobrados por utilização), e usuários premium podem usar todos os serviços (mas têm limites de taxa para prevenir uso malicioso).

Além disso, o app Assistente de IA usa o Stripe para gerir pagamentos dos usuários e tem seu próprio serviço de logs para gravar logs das operações dos usuários.

Configurações do Logto#

Primeiro, criamos recursos de API para o serviço do app Assistente de IA e criamos dois escopos, recommend:flight e predict:stock.

Depois, criamos dois papéis, free-user e paid-user, e atribuímos os escopos correspondentes:

• Atribuímos o escopo recommend:flight ao papel free-user.
• Atribuímos tanto recommend:flight quanto predict:stock ao papel paid-user.

Finalmente, criamos três usuários, free-user, prepaid-user e premium-user, e atribuímos os papéis correspondentes:

• Atribuímos o papel free-user ao usuário free-user.
• Atribuímos o papel paid-user aos usuários prepaid-user e premium-user.

Como mostrado na imagem a seguir, para implementar as informações de autorização necessárias para o cenário descrito acima, esperamos incluir as informações sobre roles, balance e numOfCallsToday do usuário atualmente conectado no JWT. Ao verificar o token de acesso no app Assistente de IA, essas informações podem ser usadas para realizar rapidamente a verificação de permissões.

Após configurar o envVariables, implementamos a função getCustomJwtClaims e clicamos no botão "Run test" para ver o resultado das claims JWT extra com base nos dados de teste atuais.

Como não configurámos os dados de teste para data.user.roles, os roles apresentados no resultado são um array vazio.

Verifica se a funcionalidade JWT personalizada está ativa#

De acordo com a configuração do Logto acima, obtivemos os resultados correspondentes no teste. Em seguida, usaremos o app de amostra fornecido pelo Logto para verificar se o nosso JWT personalizado é eficaz. Encontra o SDK com o qual estás familiarizado em Logto SDKs e implanta um app de amostra de acordo com a documentação e o repositório no GitHub correspondente.

Com base na configuração que descrevemos acima, tomando o React SDK como exemplo, precisamos atualizar a configuração correspondente no LogtoConfig:

Após conectar o usuário free_user no app de amostra que simula o app Assistente de IA, podemos ver as informações de roles, balance, numOfCallsToday, isPaidUser e isPremiumUser que adicionámos visualizando a parte do payload do token de acesso JWT.

Os valores de balance, numOfCallsToday, isPaidUser e isPremiumUser são consistentes com o teste anterior, e roles é igual a ["free-user"]. Isso é porque no processo real de login do usuário final, obteremos todos os dados acessíveis do usuário e processaremos de acordo.

Para usuários premium, podemos ver que roles é ["paid-user"] e tanto isPaidUser quanto isPremiumUser são true.

Atualizar lógica de autorização do fornecedor de serviços#

Nos passos anteriores, adicionámos claims personalizadas com base nas necessidades de negócios ao token de acesso do usuário. A seguir, podemos usar essas claims para realizar rapidamente a verificação de autorização.

Aqui fornecemos a lógica de Logto para verificar tokens de acesso JWT no lado da API. A implementação completa do código pode ser encontrada no repositório no GitHub:

Podes consultar a lógica da API de Logto para verificar tokens de acesso e personalizá-la de acordo com a tua própria lógica de negócios. Por exemplo, para o cenário do app Assistente de IA descrito aqui, podes adicionar a lógica de verificação para claims personalizadas como roles, balance, numOfCallsToday, isPaidUser e isPremiumUser na função verifyBearerTokenFromRequest.

O exemplo acima é para o cenário onde afeta o login do usuário final e a obtenção do token de acesso JWT. Se o teu caso de uso for máquina-a-máquina (M2M), também podes configurar claims JWT personalizadas para apps M2M separadamente.

Configurar JWT personalizadas para usuários não afetará o resultado das apps M2M obtendo tokens de acesso, e vice-versa.

Devido à generalidade das conexões M2M, o Logto atualmente não fornece a funcionalidade do método getCustomJwtClaims de apps M2M para aceitar dados internos do Logto. Em outros aspetos, o método de configuração de claims JWT personalizadas para apps M2M é igual ao das apps de usuários. Este artigo não vai elaborar sobre isso. Podes usar a funcionalidade de JWT personalizada do Logto para começares.

Por que usar claims JWT personalizadas?#

Fornecemos o cenário do app Assistente de IA para o John e como usar a funcionalidade de JWT personalizada do Logto para obter verificações de autorização mais flexíveis. Neste processo, podemos ver as vantagens da funcionalidade de JWT personalizada:

1. Sem a funcionalidade de JWT personalizada, os usuários precisariam solicitar um API externo (como o que fazes em getCustomJwtClaims) sempre que verificarem permissões. Para o fornecedor de serviços que fornece esse API, isso pode aumentar o encargo extra. Com a funcionalidade de JWT personalizada, essas informações podem ser colocadas diretamente no JWT, reduzindo as chamadas frequentes ao API externo.
2. Para os fornecedores de serviços, a funcionalidade de JWT personalizada pode ajudar a verificar as permissões do usuário mais rapidamente, especialmente quando o cliente chama o fornecedor de serviços com frequência, melhorando o desempenho do serviço.
3. A funcionalidade de JWT personalizada pode ajudar-te a implementar rapidamente informações adicionais de autorização requeridas pelos negócios, e as informações podem ser passadas entre o cliente e o fornecedor de serviços de maneira segura, uma vez que o JWT é autossuficiente e pode ser encriptado de modo que seja difícil de falsificar.

Ao mesmo tempo, uma vez que getCustomJwtClaims é executado sempre que um usuário precisa que o Logto emita um token de acesso, é necessário evitar a execução de lógica excessivamente complexa e pedidos de APIs externos com alta largura de banda. Caso contrário, pode levar muito tempo para o usuário final aguardar o resultado de getCustomJwtClaims durante o processo de login. Se a tua função getCustomJwtClaims retornar um objeto vazio, recomendamos fortemente que apagues temporariamente este item de configuração até que realmente precises de usá-lo.

Conclusão#

Neste artigo, o Logto estendeu o token de acesso JWT básico e estendeu a funcionalidade de claims JWT extra para permitir que os usuários coloquem informações adicionais do usuário final no token de acesso JWT de acordo com as suas necessidades de negócios, para que, após o usuário fazer login, as permissões do usuário possam ser verificadas rapidamente.

Fornecemos o cenário do app Assistente de IA do John e demonstramos como usar a funcionalidade de JWT personalizada do Logto para alcançar verificações de autorização mais flexíveis. Também apontamos alguns pontos-chave para o uso de JWT personalizadas. Em combinação com cenários de negócios reais, os usuários podem colocar várias informações relacionadas ao usuário no token de acesso JWT de acordo com as suas necessidades de negócios, para que o fornecedor de serviços possa verificar rapidamente as permissões do usuário.