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

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada. Os nomes de erro mostrados abaixo são as strings atribuídas à variável fault.name quando ocorre um erro. Consulte a seção "Variáveis de falha" abaixo para mais detalhes.

Código de falha	Status HTTP	Causa
steps.oauth.v2.InvalidFutureTimestamp	500	O carimbo de data/hora não pode estar no futuro.
steps.oauth.v2.InvalidEarlyTimestamp	500	O carimbo de data/hora não pode ser anterior a 1o de janeiro de 2014.
steps.oauth.v2.InvalidTimestamp	500	Carimbo de data/hora inválido
steps.oauth.v2.EmptyAppAndEndUserId	500	AppdId e EndUserId não podem ficar vazios.

Erros de implantação

Consulte a mensagem relatada na IU para informações sobre erros de implantação.

Variáveis de falha

Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução.

Observação: você pode usar essas variáveis para criar condições de regra de falha. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed	policy_name é o nome da política especificada pelo usuário que gerou a falha.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name é o nome da política especificada pelo usuário que gerou a falha.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name é o nome da política especificada pelo usuário que gerou a falha.	oauthV2.GetTokenInfo.cause = ClientID is Invalid

Exemplo de resposta de erro

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

Exemplo de regra de falha

<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