Como revogar e aprovar tokens

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Noções básicas sobre a revogação de token

Em alguns casos, os apps precisam revogar ou invalidar explicitamente tokens individuais. Um caso típico pode ser quando um usuário sai de um aplicativo compatível com OAuth. Um token revogado não será mais útil para autorização. Depois que um token for revogado, se um app apresentar esse token a um proxy de API, uma política OAuthV2 com uma operação "VerifyAccessToken" o rejeitará.

O padrão de revogação de token é definido pelo IETF RFC 7009, a especificação de revogação de tokens do OAuth 2.0.

Em vez de revogar tokens específicos, é possível revogar os IDs do cliente ou apps inteiros do desenvolvedor. Para mais detalhes, consulte Como revogar e aprovar chaves de apps do desenvolvedor. Em comparação com a revogação de um token individual, a revogação de um ID do cliente ou app do desenvolvedor tem um impacto mais amplo. Quando você revogar um ID do cliente ou um app de desenvolvedor, a Apigee rejeitará todos os tokens associados a esse ID de cliente ou app de desenvolvedor e não emitirá mais novos tokens para esse ID de cliente ou app para desenvolvedores.

Depois de revogar um token de acesso ou de atualização, é possível aprová-lo novamente a qualquer momento antes do vencimento. Depois disso, a política do OAuthV2 da Apigee aceitará novamente o token para autorização até que ele expire. A expiração do token independe do estado aprovado ou revogado. A política OAuthV2 da Apigee com operação de ValidateAccessToken aceitará um token de acesso somente se esse token for aprovado (ou não revogado) e não expirado. Da mesma forma, a política OAuthV2 da Apigee com uma operação RefreshAccessToken aceitará um token de atualização somente se esse token for aprovado (ou não revogado) e não expirado.

É possível usar duas políticas que podem ser usadas para revogar tokens:

A política OAuthV2 pode revogar e também restabelecer um único token por vez. A política RevokeOAuthV2 é mais flexível, porque pode revogar vários tokens de uma só vez, por ID do aplicativo ou ID do usuário final. O restante desta página descreve o uso da política OAuthV2 para revogar um token ou restaurar um token revogado anteriormente.

Como revogar tokens de acesso e de atualização

Veja um exemplo de configuração para a política OAuthV2 que usa a operação InvalidateToken. Nesse caso, como o atributo cascade no elemento Token é verdadeiro, a Apigee revoga o token de acesso e o token de atualização associado.

  <OAuthV2 name="InvalidateToken">
    <Operation>InvalidateToken</Operation>
    <Tokens>
      <Token type="accesstoken" cascade="true">request.queryparam.token</Token>
    </Tokens>
  </OAuthV2>

Para mais informações sobre como a sinalização de cascata funciona, consulte a seção abaixo sobre os atributos do elemento Token.

Elemento <Tokens>/<Token>

Identifica a variável de fluxo que especifica o token a ser revogado. Se espera-se que os desenvolvedores enviem uma solicitação de revogação usando um parâmetro de consulta chamado access_token, por exemplo, a variável de fluxo correta será: request.queryparam.access_token. Para exigir o token em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.access_token.

Não é possível revogar um token de acesso que esteja no formato JWT. Além disso, não é possível usar a política OAuthV2 para revogar um token de atualização associado a um token de acesso que esteja no formato JWT. Um erro de ambiente de execução ocorrerá se a variável de contexto especificada aqui se referir a um token de acesso JWT ou a um token de atualização associado a um token de acesso JWT. É possível revogar os tokens de atualização associados a tokens de acesso JWT usando a política RevokeOAuthV2.

Atributos

  • type (obrigatório, string): o tipo de token identificado pela variável especificada. Os valores aceitos são accesstoken e refreshtoken:
    • Para revogar um token de acesso, especifique o tipo accesstoken.
    • Para revogar os tokens de acesso e de atualização, especifique o tipo refreshtoken. Ao ver o tipo refreshtoken, a Apigee presume que é um token de atualização. Se esse token de atualização for encontrado, ele será revogado. Se esse token de atualização não for encontrado, a Apigee verificará se ele é um token de acesso. Se o token de acesso existir, ele será revogado.

      Observação: se você passar um token já invalidado para uma política InvalidateToken, a política não retornará um erro, mesmo que você espere por um. Essa operação não tem efeito.
  • cascade (opcional, booleano, padrão: verdadeiro) O uso principal desse atributo é revogar um token de atualização sem revogar o token de acesso associado a ele. Considere estes casos:
    • Revogue apenas um token de atualização e não revogue o token de acesso associado. Para fazer isso, defina o tipo de <Token> como refreshtoken e defina a cascata como false.
    • Revogue o token de acesso e o token de atualização. Para isso, defina o tipo <Token> como accesstoken. O valor de cascata pode ser true (o padrão) ou false. Se você defini-lo como true, o token de acesso e o token de atualização serão revogados. Se você defini-lo como false, o token de acesso será revogado e o token de atualização não poderá ser usado. Veja mais detalhes na observação abaixo.
    • Revogue um token de acesso e não revogar o token de atualização associado. Não compatível. Veja mais detalhes na observação abaixo.

Observação: por motivos de segurança, se você revogar um token de acesso, o token de atualização associado também será revogado. Portanto, não é possível usar o atributo cascata para revogar apenas um token de acesso. Por exemplo, se você definir o tipo <Token> como accesstoken e definir cascade=false, o token de acesso será revogado (conforme esperado). No entanto, o token de atualização associado não pode ser usado. Ele não pode ser usado para atualizar o token de acesso revogado. O principal caso de uso do atributo em cascata é quando você quer revogar apenas um token de atualização. Nesse caso, defina o tipo <Token> como refreshtoken e defina cascade=false. O token de atualização será revogado, mas o token de acesso associado permanecerá válido, até que ele expire ou seja revogado. Para mais informações, consulte esta discussão do fórum da comunidade.

Como aprovar tokens de acesso e de atualização

Use a operação ValidateToken para "reaprovar" um token revogado. Ou seja, quando você aplicar essa operação, o status do token de acesso ou atualização será alterado de "revogado" para "aprovado". Você pode validar qualquer token revogado que ainda não tenha expirado.

<OAuthV2 name="ValidateToken">
  <Operation>ValidateToken</Operation>
  <Tokens>
    <Token type="refreshtoken" cascade="true">flow.variable</Token>
  </Tokens>
</OAuthV2>

Elemento <Tokens>/<Token>

Identifica a variável de fluxo que especifica o token a ser validado. Se espera-se que os desenvolvedores enviem uma solicitação de validação usando um parâmetro de consulta chamado access_token, por exemplo, a variável de fluxo correta será: request.queryparam.access_token. Para exigir o token em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.access_token.

Atributos

  • type (obrigatório, string) O tipo de token identificado pela variável especificada. Os valores aceitos são accesstoken e refreshtoken.
  • cascade (opcional, booleano): por padrão, essa opção é definida como true, e faz com que a validação seja propagada para os tokens associados. Portanto, se aplicado a um token de atualização, o token de acesso associado a ele também será validado Se aplicado a um token de acesso, o token de atualização associado também será validado. Se você definir essa opção como false, somente o token especificado de acesso ou de atualização será validado.