Explorando concessões de OIDC: entendendo e solucionando o erro "invalid_grant"

Contexto#

Em nossa comunidade, frequentemente ouvimos uma pergunta recorrente de nossos usuários: Qual é o problema com o erro "invalid_grant" no Logto? Como #503

Este é um desafio comum e um bloqueio para alguns de nossos usuários ao integrar o Logto em suas próprias aplicações. No entanto, as razões por trás deste erro variam de caso para caso, e às vezes é difícil explicar com o contexto limitado fornecido. Portanto, entender o conceito OIDC exato e aprender a maneira de solucionar o problema é essencial para todos.

Agora vamos mergulhar nos fundamentos das concessões de OIDC.

Concessões de OIDC explicadas#

Como introduzimos em um post de blog anterior, OpenID Connect (OIDC) é um protocolo construído em cima de OAuth 2.0.

No contexto de OIDC ou OAuth2, um concessão é um conjunto de permissões concedidas pelo proprietário do recurso (geralmente o usuário) a um aplicativo cliente. As concessões são essenciais para que o aplicativo cliente acesse as informações de identidade do usuário e outros recursos protegidos. OIDC define vários tipos de concessão, cada um adequado para um cenário diferente e a maneira como um aplicativo obtém um token de acesso.

Aqui está uma analogia para ajudar você a entender melhor as concessões de OIDC.

Imagine que você está viajando para diferentes países, e cada país exige um carimbo de visto para entrada. Nesse cenário, seu passaporte serve como sua conta de usuário, contendo suas informações pessoais. As concessões de OIDC são como as maneiras de aplicar para um visto para entrar em um país. Quando um visto é emitido para você, você essencialmente obtém o "token" para entrar nesse país.

Da mesma forma, ao usar um aplicativo, a solicitação de concessão é a ação que você solicita para o servidor de autorização conceder-lhe acesso. O servidor de autorização valida sua identidade e emite o "visto" (token de acesso) para entrar no aplicativo.

Tipos de concessão de OIDC mais usados:#

1. Concessão do Código de Autorização: Este é o tipo de concessão mais comumente usado em OIDC. Envolve redirecionar o usuário para um servidor de autorização, obter um código de autorização, redirecionar de volta para o aplicativo e trocar o código por um token de acesso. Pense nisso como o processo padrão de solicitar um visto na embaixada antes de entrar em um país estrangeiro.
2. Concessão do Token de Atualização: No OIDC, este tipo de concessão permite que um aplicativo cliente obtenha um novo token de acesso usando um token de atualização que foi emitido anteriormente. É comumente usado para estender uma sessão de usuário sem exigir que eles reinsiram suas credenciais. Imagine que seu visto vem com um cartão mágico que permite que você estenda sua estadia no país estrangeiro sem passar pela alfândega novamente.
3. Concessão Implícita: Este tipo de concessão é usado para aplicações legadas baseadas em navegador e é menos seguro do que a Concessão do Código de Autorização. Ele retorna o token de acesso diretamente para o aplicativo cliente. Funciona como um "visto na chegada", pois não é necessária nenhuma aplicação de visto prévia.
4. Concessão de Credenciais de Cliente: Adequado para comunicação de servidor para servidor, este tipo de concessão permite que um aplicativo cliente se autentique diretamente com o servidor de autorização usando suas credenciais (ID do cliente e segredo do cliente). É semelhante a um agente especial mostrando um distintivo de trabalho especial para entrar no país sem passar pelo processo de solicitação de visto.

Modelo de objeto de concessão:#

No Logto, a concessão é persistida no banco de dados como uma entidade objeto, contendo informações como ID da conta do usuário, ID do aplicativo, recursos OIDC associados e escopos, tempo de expiração, e mais. Cada token de atualização e token de acesso está associado a um objeto de concessão específico.

Solicitações de concessão:#

Solicitações HTTP feitas ao servidor de autorização por meio de APIs. Um aplicativo cliente pode enviar solicitações de concessão para o endpoint de token OIDC para diversos fins, incluindo a solicitação de uma nova concessão (por exemplo, assinando e obtendo tokens de atualização e acesso), atualizando os detalhes da concessão (por exemplo, trocando um token de atualização por um novo token de acesso), ou revogando uma concessão (por exemplo, revogando todos os tokens emitidos para usuários logados e terminando seu acesso).

Uma solicitação de concessão de código de autorização típica se parece com o seguinte:

Compreendendo o erro "invalid_grant"#

Encontrar um erro invalid_grant em OIDC normalmente indica que o tipo de concessão ou os dados associados à solicitação de concessão são inválidos ou não suportados. Aqui estão algumas razões comuns por trás deste erro:

1. Tipo de concessão incorreto: Usar o tipo de concessão errado para o seu aplicativo pode resultar em um erro invalid_grant. Certifique-se de que está usando o tipo de concessão apropriado, utilizando os SDKs do Logto.
2. URIs de redirecionamento incompatíveis: Ao trocar um código de autorização por tokens, a URI de redirecionamento usada na solicitação deve corresponder àquela usada durante a solicitação de autorização inicial. Uma incompatibilidade pode resultar em um erro invalid_grant.
3. Código de autorização expirado ou consumido: No fluxo de registro do Código de Autorização, o código de autorização tem um prazo de validade limitado, e será marcado como "consumido" uma vez usado para adquirir tokens. Tentar trocar um código expirado ou consumido por um token de acesso resultará em um erro invalid_grant.
4. Token de atualização expirado ou rodado: Ao trocar um token de atualização por um token de acesso, o erro invalid_grant ocorre se o token de atualização já estiver vencido. Além disso, para maior segurança, o Logto habilita a rotação do token de atualização por padrão. Solicitar o endpoint do token com o mesmo token de atualização uma segunda vez é considerado o uso de um token de atualização "rodado" e será rejeitado.
5. Dados obrigatórios em falta ou cabeçalhos da solicitação: Ao compor uma solicitação de concessão, os parâmetros obrigatórios e os cabeçalhos da solicitação devem ser fornecidos para o tipo de concessão dado. Por exemplo, o ID do cliente deve ser fornecido em todas as solicitações de concessão, e ID do cliente e segredo do cliente devem ser fornecidos para a Concessão de Credenciais do Cliente. Este risco também pode ser mitigado, utilizando os SDKs do Logto.6. Outras razões: Este erro também pode ocorrer devido a razões como incompatibilidade de credenciais do cliente, concessão expirada ou não encontrada, token de atualização não encontrado, etc.

Solução de problemas#

Algumas dicas para solucionar efetivamente o erro "invalid_grant":

1. Sempre use um SDK do Logto para integrar o Logto em seu aplicativo, a fim de garantir que a solicitação de concessão está sendo feita para o respectivo endpoint e com os dados corretos.
2. Verifique se as credenciais do seu aplicativo e as URIs de redirecionamento correspondem às configurações no Console de Administração.
3. Evite fazer solicitações redundantes, especialmente para SPAs como React e Vue, onde os componentes da página podem ser renderizados novamente devido às alterações de dependência. Certifique-se de que as funções usadas para trocar códigos ou tokens de atualização por tokens de acesso não são acionadas várias vezes com os mesmos parâmetros de solicitação. Este é um erro comum cometido por alguns de nossos usuários. Normalmente, se você pode ver várias solicitações "token" em seu console de depuração, a primeira é bem-sucedida, mas as subsequentes falham, verifique os parâmetros de suas solicitações para ver se estão usando o mesmo "código" ou "token de atualização". Lembre-se, você só pode usar um código e token de atualização UMA vez nas solicitações de concessão.
4. Verifique os tempos de expiração. Por exemplo, se o seu token de atualização estiver expirado (por padrão, 14 dias) e você receber o erro invalid_grant, você deve lidar com isso corretamente, iniciando novamente um fluxo de sign-in do usuário. Se estiver usando o SDK Logto, você pode chamar a função signIn() novamente para redirecionar seus usuários de volta para a página de sign-in.
5. Monitore logs de auditoria. Vá para Console de Administração → Logs de Auditoria, encontre o log de erro associado ao incidente e verifique a pilha de erros detalhada. Normalmente, há uma razão mais específica na pilha de erros por trás do erro invalid_grant, como "Concessão não encontrada" ou "Token de atualização expirado".

Notas finais#

O erro invalid_grant pode ser desafiador e confuso para os iniciantes, mas com uma clara compreensão das concessões de OIDC e atenção aos detalhes, você pode identificar e lidar com o problema sozinho. Junte-se às nossas discussões no Discord ou no GitHub, e nos informe se este blog ajudou a esclarecer a confusão e identificar os problemas que você está enfrentando. A equipe de desenvolvimento do Logto está sempre disposta a ajudá-lo.

Juntos, vamos construir uma experiência de autenticação integrada e segura para suas aplicações amadas.