Revogar e aprovar tokens

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Compreender a revogação de tokens

Em alguns casos, as apps têm de revogar ou invalidar explicitamente tokens individuais. Um caso típico pode ser quando um utilizador termina sessão numa app com OAuth. Um token revogado deixa de ser útil para autorização. Depois de um token ser revogado, se uma app apresentar esse token a um proxy de API, uma política OAuthV2 com uma operação de VerifyAccessToken rejeita esse token.

A norma para a revogação de tokens é definida pela IETF RFC 7009, a especificação de revogação de tokens OAuth 2.0.

Em alternativa à revogação de tokens específicos, pode revogar IDs de clientes ou apps de programadores inteiras. Consulte o artigo Revogar e aprovar chaves de apps de programadores para ver detalhes. Em comparação com a revogação de um token individual, a revogação de um ID do cliente ou de uma app de programador tem um impacto mais amplo. Quando revoga um ID de cliente ou uma app de programador, o Apigee rejeita todos os tokens associados a esse ID de cliente ou app de programador e deixa de emitir novos tokens para esse ID de cliente ou app de programador.

Depois de revogar um token, seja um token de acesso ou um token de atualização, pode, opcionalmente, voltar a aprovar esse token em qualquer altura antes de expirar. Depois de voltar a aprovar o token, a política OAuthV2 do Apigee volta a aceitar esse token para autorização até o token expirar. A expiração do token é independente do estado aprovado ou revogado do token. A política OAuthV2 do Apigee com uma operação de ValidateAccessToken aceita um token de acesso apenas se esse token for aprovado (ou não revogado) e não tiver expirado. Da mesma forma, a política OAuthV2 do Apigee com uma operação de RefreshAccessToken aceita um token de atualização apenas se esse token for aprovado (ou não revogado) e não tiver expirado.

Existem duas políticas que pode usar para revogar tokens:

A política OAuthV2 tem a capacidade de revogar e também repor um único token de cada vez. A política RevokeOAuthV2 é mais flexível, pois pode revogar vários tokens de uma só vez, por ID da app ou ID do utilizador final. O resto desta página descreve a utilização da política OAuthV2 para revogar um token ou repor um token revogado anteriormente.

Revogar chaves de acesso e símbolos de atualização

Segue-se um exemplo de configuração para a política OAuthV2 que usa a operação InvalidateToken. Neste caso, uma vez que o atributo cascade no elemento Token é verdadeiro, o Apigee revoga a chave de acesso e a respetiva chave de atualização associada.

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

Para mais informações sobre o funcionamento da flag de cascata, consulte a secçã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 os programadores tiverem de enviar um pedido de revogação através de um parâmetro de consulta denominado access_token, por exemplo, a variável de fluxo correta é: request.queryparam.access_token. Para exigir o token num cabeçalho HTTP, por exemplo, defina este valor como request.header.access_token.

Não é possível revogar uma chave de acesso 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 no formato JWT. Ocorre um erro de tempo de execução 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. Pode revogar tokens de atualização associados a tokens de acesso JWT através da política RevokeOAuthV2.

Atributos

  • type (obrigatório, string): o tipo de token identificado pela variável especificada. Os valores suportados são accesstoken e refreshtoken:
    • Para revogar um token de acesso, especifique o tipo accesstoken.
    • Para revogar as chaves de acesso e os símbolos de atualização, especifique o tipo refreshtoken. Quando vê o tipo refreshtoken, o Apigee assume que o token é um token de atualização. Se esse símbolo de atualização for encontrado, é revogado. Se esse token de atualização não for encontrado, o Apigee verifica se é um token de acesso. Se a chave de acesso existir, é revogada.

      Nota: se transmitir um token já invalidado a uma política InvalidateToken, a política não devolve um erro, embora possa esperar que o faça. Essa operação não tem efeito.
  • cascade (opcional, booleano, predefinição: true) A utilização principal deste atributo é revogar uma chave de atualização sem revogar a chave de acesso associada. Considere estes casos:
    • Revogar apenas um token de atualização e não revogar o token de acesso associado. Para tal, defina o tipo <Token> como refreshtoken e defina a cascata como false.
    • Revogue o token de acesso e o token de atualização. Para tal, defina o tipo de <Token> como accesstoken. O valor de cascade pode ser true (o valor predefinido) ou false. Se a definir como true, a chave de acesso e a chave de atualização são revogadas. Se o definir como false, a chave de acesso é revogada e o token de atualização fica inutilizável. Consulte a nota abaixo para mais explicações.
    • Revogar uma chave de acesso e não revogar a chave de atualização associada. Não suportado. Consulte a nota abaixo para mais explicações.

Nota: por motivos de segurança, se revogar uma chave de acesso, a chave de atualização associada também é revogada. Por conseguinte, não pode usar o atributo de cascata para revogar apenas um token de acesso. Por exemplo, se definir o tipo <Token> como accesstoken e definir cascade=false, a chave de acesso é revogada (conforme esperado); no entanto, a chave de atualização associada é inutilizável. Não pode ser usado para atualizar a chave de acesso revogada. O exemplo de utilização principal do atributo de cascata é quando quer apenas revogar um token de atualização. Nesse caso, defina o tipo de <Token> como refreshtoken, e defina cascade=false. O token de atualização é revogado, mas o token de acesso associado permanece válido (até expirar ou ser revogado). Para mais informações, consulte esta discussão do fórum da comunidade.

Aprovar chaves de acesso e símbolos de atualização

Use a operação ValidateToken para "reaprovar" um token revogado. Ou seja, quando aplica esta operação, o estado do token de acesso ou de atualização segmentado é alterado de "revoked" (revogado) para "approved" (aprovado). 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 validar. Se os programadores tiverem de enviar um pedido de validação através de um parâmetro de consulta denominado access_token, por exemplo, a variável de fluxo correta será: request.queryparam.access_token. Para exigir o token num cabeçalho HTTP, por exemplo, defina este valor como request.header.access_token.

Atributos

  • type (obrigatório, string) O tipo de token identificado pela variável especificada. Os valores suportados são accesstoken e refreshtoken.
  • cascade (opcional, booleano): por predefinição, esta opção está definida como true e faz com que a validação seja propagada para os tokens associados. Assim, se for aplicado a um token de atualização, o token de acesso associado também é validado. Se for aplicado a um token de acesso, o respetivo token de atualização associado também é validado. Se definir esta opção como false, apenas o acesso especificado ou o token de atualização é validado.