Inspeção de token OAuth 2.0

A inspeçã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 determinado 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 acesse o recurso protegido.

Esses metadados incluem:

• Se o token está atualmente ativo (ou se expirou ou foi revogado)
• As permissões que o token de acesso concede (normalmente transmitidas por meio 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 ele foi emitido)

A introspecção de token permite que o recurso protegido consulte essas informações, independentemente de estarem contidas dentro do próprio token.

Existem dois tipos de tokens de acesso, dependendo de como eles 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 por criptografia para evitar adulteração. JSON Web Token (JWT) é o padrão comum para este método.

Para tokens autônomos, os metadados relacionados à autorização podem ser analisados diretamente 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/recuperar os metadados.

Solicitação de introspecção de token#

Usar tokens de acesso baseados em identificador requer verificação com o servidor de autorização por meio de uma solicitação de rede. Existe um protocolo padrão para isso chamado Introspecção de Token OAuth 2.0 (RFC 7662).

O recurso protegido irá POSTar o token no endpoint de introspecção do servidor de autorização e, em retorno, receberá um objeto JSON contendo os parâmetros do token.

Observe que solicitações de introspecção não podem ser iniciadas arbitrariamente; elas devem atender a uma das seguintes condições:

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

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

Abaixo está um exemplo de uma solicitação de introspecção, onde o recurso protegido autentica usando um ID de cliente e um segredo de cliente, que foram obtidos após o registro como um cliente OAuth junto ao servidor de autorização.

Abaixo está um exemplo de uma solicitação de introspecção que usa diretamente um token de acesso. O token de acesso pode ser obtido diretamente do endpoint /token usando as credenciais de um app de máquina a máquina registrado 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 do 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:

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

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