Revogar a política do OAuth V2

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

Confira a documentação da Apigee Edge.

O recurso de token de acesso JWT está disponível para a Apigee e para a Apigee híbrida, versões 1.7.0 e mais recentes. Consulte Como usar tokens OAuth do JWT.

Visão geral

Revoga os tokens de acesso do OAuth2 associados a um ID de aplicativo de desenvolvedor ou a um ID de usuário final do aplicativo ou a ambos.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Aviso: os tokens OAuth são armazenados em cache por três minutos (180 segundos). Portanto, um token revogado ainda pode ter sucesso por até três minutos, até que o limite de cache expire.

Aviso: é possível revogar um grande número de tokens com uma única execução dessa política. Como não é possível desfazer a revogação de um token, verifique se o ID transmitido na política especificando os tokens que serão revogados está correto.

Use a política OAuthv2 para gerar um token de acesso do OAuth 2.0. Um token gerado pela Apigee tem o seguinte formato:

{
  "issued_at" : "1421847736581",
  "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[PremiumWeatherAPI]",
  "expires_in" : "3599", //--in seconds
  "developer.email" : "[e-mail]",
  "organization_id" : "0",
  "token_type" : "BearerToken",
  "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
  "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
  "organization_name" : "myorg",
  "refresh_token_expires_in" : "0", //--in seconds
  "refresh_count" : "0"
}

O elemento application_name contém o ID do app do desenvolvedor associado ao token.

Por padrão, a Apigee não inclui o ID do usuário final no token. É possível configurar a Apigee para incluir o ID do usuário final adicionando o elemento <AppEndUser> à política OAuthv2:

<OAuthV2 name="GenerateAccessTokenClient">
    <Operation>GenerateAccessToken</Operation>
    ...
    <AppEndUser>request.queryparam.app_enduser</AppEndUser>
</OAuthV2>

Neste exemplo, transmita o ID do usuário final à política do OAuthv2 em um parâmetro de consulta chamado app_enduser. O ID do usuário final é então incluído no token no elemento app_enduser:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "[e-mail]",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

Revogar por código do aplicativo do desenvolvedor

Revogue os tokens de acesso do OAuth2 associados a um ID de aplicativo de desenvolvedor. Todos os tokens de acesso do OAuth2 gerados pela Apigee incluem o ID do aplicativo para desenvolvedores associado ao token. Revogue os tokens com base no ID do aplicativo.

Para ver uma lista de IDs de aplicativo de um desenvolvedor específico, use:

• API Método: organizations.developers.apps.list para ver uma lista de apps associados a um desenvolvedor.
• API Método: organizations.developers.apps.get para ver detalhes sobre o aplicativo, incluindo o ID dele.

Revogar por código de usuário final do aplicativo

Revogar os tokens de acesso do OAuth2 associados a um ID de usuário final específico do aplicativo. Esse é o token associado ao ID do usuário para o qual os tokens foram emitidos.

Por padrão, não há campo para o ID de usuário final no token de acesso do OAuth. Se quiser ativar a revogação de tokens de acesso do OAuth 2.0 por ID do usuário final, configure a política do OAuthv2 para incluir o ID do usuário no token, conforme mostrado acima.

Para ver um ID de usuário final do aplicativo, use o método: organizations.developers.get.

Amostras

Os exemplos a seguir usam a política "Revogar OAuth V2" para revogar tokens de acesso OAuth2.

Código do aplicativo do desenvolvedor

Para revogar os tokens de acesso pelo ID do app do desenvolvedor, use o elemento <AppId> na sua política.

O exemplo a seguir espera encontrar o ID do app do desenvolvedor do token de acesso em um parâmetro de consulta chamado app_id:

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
</RevokeOAuthV2>

Com o ID do app de desenvolvedor, a política revoga o token de acesso.

Revogar antes do carimbo de data/hora

Para revogar tokens de acesso por ID do app do desenvolvedor gerados antes de uma data e hora específicas, use o elemento <RevokeBeforeTimestamp> na sua política. <RevokeBeforeTimestamp> especifica um período de tempo UTC em milissegundos. Todos os tokens emitidos antes desse tempo são revogados.

O exemplo a seguir revoga os tokens de acesso de um app de desenvolvedor criado antes de 1º de julho de 2019:

<RevokeOAuthV2 continueOnError="false" enabled="true" name="MyRevokeTokenPolicy">
  <DisplayName>Revoke OAuth v2.0-1</DisplayName>
  <AppId ref="request.queryparam.app_id"></AppId>
  <RevokeBeforeTimestamp>1561939200000</RevokeBeforeTimestamp>
</RevokeOAuthV2>

O elemento <RevokeBeforeTimestamp> usa um inteiro de 64 bits (tamanho) que representa o número de milissegundos decorridos desde a meia-noite, em 1 de janeiro de 1970, em UTC.

---

Referência de elemento

A referência de elementos descreve os elementos e atributos da política RevokeOAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<RevokeOAuthV2 continueOnError="false" enabled="true" name="GetOAuthV2Info-1">
  <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
  <AppId ref="variable"></AppId>
  <EndUserId ref="variable"></EndUserId>
  <RevokeBeforeTimestamp ref="variable"></RevokeBeforeTimestamp>
  <Cascade>false</Cascade>
</RevokeOAuthV2>

Atributos <RevokeOAuthV2>

<RevokeOAuthV2 continueOnError="false" enabled="true" name="Revoke-OAuth-v20-1">

A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:

Atributo	Descrição	Padrão	Presence
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
continueOnError	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar.	false	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	true	Opcional

Elemento <DisplayName>

Use em conjunto com o atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.

<DisplayName>Policy Display Name</DisplayName>

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo name da política.
Presence	Opcional
Tipo	String

Elemento <AppId>

Especifica o ID de app do desenvolvedor dos tokens a serem revogados. Transmita uma variável que contenha o ID do aplicativo ou o ID do aplicativo literal.

<AppId>appIdString</AppId>

or:

<AppId ref="request.queryparam.app_id"></AppId>

Padrão	request.formparam.app_id (um x-www-form-urlencoded e especificado no corpo da solicitação)
Presence	Opcional
Tipo	String
Valores válidos	Uma variável de fluxo que contém uma string de ID do aplicativo ou uma string literal.

Elemento <Cascade>

Se true e você tiver um token de acesso opaco tradicional, o token de atualização e o token de acesso serão revogados se <AppId> ou <EndUserId> corresponderem. Se você tiver um token de acesso JWT, apenas o token de atualização emitido com o token de acesso será revogado. Por padrão, os tokens de acesso JWT não podem ser revogados. Se for false, apenas o token de acesso será revogado e o token de atualização permanecerá inalterado. O mesmo comportamento se aplica apenas a tokens de acesso opacos. Os tokens de acesso JWT não podem ser revogados.

<Cascade>false<Cascade>

Padrão	false
Presence	Opcional
Tipo	Booleano
Valores válidos	true ou false

Elemento <EndUserId>

Especifica o ID do usuário final do aplicativo do token a ser revogado. Transmita uma variável que contenha o ID do usuário ou uma string de token literal.

<EndUserId>userIdString</EndUserId>

or:

<EndUserId ref="request.queryparam.access_token"></EndUserId>

Padrão	request.formparam.enduser_id (um x-www-form-urlencoded e especificado no corpo da solicitação)
Presence	Opcional
Tipo	String
Valores válidos	Uma variável de fluxo que contém uma string de ID de usuário ou uma string literal.

Elemento <RevokeBeforeTimestamp>

Revogue os tokens emitidos antes do carimbo de data/hora. Esse elemento funciona com <AppId> e <EndUserId> para permitir que você revogue os tokens antes de um horário específico. O valor padrão é o tempo em que a política é executada.

<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

<RevokeBeforeTimestamp ref="request.queryparam.revoke_since_timestamp"></RevokeBeforeTimestamp>

Padrão	O carimbo de data/hora em que a política é executada.
Presence	Opcional
Tipo	Número inteiro de 64 bits (longo) que representa o número de milissegundos decorridos desde a meia-noite de 1º de janeiro de 1970 UTC.
Valores válidos	Uma variável de fluxo que contém um carimbo de data/hora ou um carimbo de data/hora literal. O carimbo de data/hora não pode estar no futuro nem ser anterior a 1º de janeiro de 2014.

Variáveis de fluxo

A política RevoteOAuthV2 não define variáveis de fluxo.

Referência de erros

This section describes the fault codes and error messages that are returned and fault variables that are set by Apigee when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes. The error names shown below are the strings that are assigned to the fault.name variable when an error occurs. See the Fault variables section below for more details.

Fault code	HTTP status	Cause
steps.oauth.v2.InvalidFutureTimestamp	500	Timestamp cannot be in the future.
steps.oauth.v2.InvalidEarlyTimestamp	500	Timestamp cannot be earlier than January 1, 2014.
steps.oauth.v2.InvalidTimestamp	500	Timestamp is invalid.
steps.oauth.v2.EmptyAppAndEndUserId	500	Both AppdId and EndUserId cannot be empty.

Deployment errors

Refer to the message reported in the UI for information about deployment errors.

Fault variables

These variables are set when this policy triggers an error at runtime.

Note: You an use these variables to create Fault Rule conditions. For more information, see What you need to know about policy errors.

Variables	Where	Example
fault.name="fault_name"	fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code.	fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name is the user-specified name of the policy that threw the fault.	oauthV2.GetTokenInfo.cause = ClientID is Invalid

Example error response

{
   "fault":{
      "faultstring":"Timestamp is in the future.",
      "detail":{
         "errorcode":"steps.oauth.v2.InvalidFutureTimestamp"
      }
   }
}

Example fault rule

<FaultRule name="RevokeOAuthV2 Faults">
    <Step>
        <Name>AM-InvalidTimestamp</Name>
    </Step>
    <Condition>(fault.name = "InvalidFutureTimestamp")</Condition>
</FaultRule>

Temas relacionados

• Política do OAuthV2
• Página inicial do OAuth
• Como personalizar tokens e códigos de autorização