Introspecção de token OAuth 2.0

Introspecção de token OAuth 2.0 define um método que permite que um recurso protegido autorizado consulte o servidor de autorização para determinar os metadados associados a um dado token (seja um token de acesso ou um token de atualização), fornecido por um cliente OAuth. Com base nos metadados do token específico, permite que o proprietário do recurso aceda ao recurso protegido.

Estes metadados incluem:

• Se o token está atualmente ativo (ou se expirou ou foi revogado)
• As permissões que o token de acesso concede (geralmente transmitidas através de escopos OAuth 2.0)
• O contexto de autorização no qual o token foi concedido (incluindo quem autorizou o token e para qual cliente foi emitido)

A introspecção de token permite que o recurso protegido consulte esta informação, independentemente de estar contida dentro do token em si.

Existem dois tipos de tokens de acesso, dependendo de como são codificados:

• Baseado em identificador: O token representa um identificador aleatório, difícil de adivinhar, associado à autorização no banco de dados do servidor de autorização.
• Autónomo: A autorização é codificada dentro do próprio token e é protegida através de criptografia para prevenir adulterações. JSON Web Token (JWT) é o padrão comum para este método.

Para tokens autónomos, os metadados relacionados à autorização podem ser diretamente analisados a partir do token de acesso. No entanto, para tokens baseados em identificador, a funcionalidade de introspecção de token do servidor de autorização deve ser usada para validar/obter os metadados.

Pedido de introspecção de token#

O uso de tokens de acesso baseados em identificador requer verificação com o servidor de autorização via um pedido de rede. Existe um protocolo padrão para isso chamado OAuth 2.0 Introspecção de Token (RFC 7662).

O recurso protegido irá POST o token para o ponto final de introspecção do servidor de autorização e, em retorno, ele receberá um objeto JSON contendo os parâmetros do token.

Note que pedidos de introspecção não podem ser iniciados arbitrariamente; devem satisfazer uma das seguintes condições:

• Autenticação utilizando credenciais (que devem estar pré-registradas com o servidor de autorização), ou
• Autorização utilizando um token de acesso.

Como resultado, nesta interação específica, o recurso protegido torna-se o cliente OAuth, e o servidor de autorização torna-se o recurso protegido.

Abaixo está um exemplo de um pedido de introspecção, onde o recurso protegido autentica usando um ID de cliente e um segredo de cliente, que foram obtidos após o registo como um cliente OAuth com o servidor de autorização.

Abaixo está um exemplo de um pedido de introspecção que utiliza diretamente um token de acesso. O token de acesso pode ser obtido diretamente do ponto final /token usando as credenciais de um app registado máquina-para-máquina e o tipo de concessão client_credentials.

Resposta de introspecção de token#

O parâmetro mais importante é active, que é um valor booleano. Se true, indica que o token é válido, e o objeto JSON incluirá outros detalhes do token, como os valores de escopo. Se false, o token é inválido ou expirado, e o recurso protegido deve retornar uma resposta 401 Unauthorized com o código de erro invalid_token.

Aqui está um exemplo de resposta para um token válido:

Além de active, que é obrigatório, todos os outros parâmetros são opcionais.

O recurso protegido pode usar estes campos adicionais para determinar permissões de acesso, de maneira semelhante a como analisaria e validaria um token de acesso JWT.