Revogar a política do OAuth V2

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

Confira a documentação da Apigee Edge.

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.

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" : "tesla@weathersample.com",
  "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" : "tesla@weathersample.com",
 "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 Presença

Atributo	Descrição	Padrão	Presença
`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.	falso	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.	verdadeiro	Opcional

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.

falso

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.

verdadeiro

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

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

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

Presença 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)
Presença	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	falso
Presença	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)
Presença	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.
Presença	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.

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>