Revogue a política de OAuth V2

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

Veja a documentação do Apigee Edge.

A funcionalidade de token de acesso JWT está disponível para o Apigee e para o Apigee Hybrid versões 1.7.0 e posteriores. Consulte o artigo Usar tokens OAuth JWT.

Vista geral

Revoga os tokens de acesso OAuth2 associados a um ID de app de programador ou a um ID de utilizador final da app, ou ambos.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Aviso: os tokens OAuth são colocados em cache durante três minutos (180 segundos). Por conseguinte, um token revogado pode continuar a funcionar durante um máximo de três minutos, até o limite da cache expirar.

Aviso: pode revogar um grande número de tokens com uma única execução desta política. Uma vez que não pode anular a revogação de um token, certifique-se de que o ID que transmite a esta política que especifica os tokens a revogar está correto.

Use a política OAuthv2 para gerar uma chave de acesso OAuth 2.0. Um token gerado pelo 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 da app de programador associado ao token.

Por predefinição, o Apigee não inclui o ID do utilizador final no token. Pode configurar o Apigee para incluir o ID do utilizador 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 utilizador final para a política OAuthv2 num parâmetro de consulta denominado app_enduser. O ID do utilizador final é, em seguida, 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"
}

Revogação por ID da app do programador

Revogue tokens de acesso OAuth2 associados a um ID da app de programador. Todas as chaves de acesso OAuth2 geradas pelo Apigee incluem o ID da app de programador associada à chave. Em seguida, pode revogar tokens com base nesse ID da app.

Para obter uma lista de IDs de apps de um programador específico, use o seguinte:

• Método: organizations.developers.apps.list API para obter uma lista de apps associadas a um programador.
• API Method: organizations.developers.apps.get para obter detalhes sobre a app, incluindo o ID da app.

Revogue por ID do utilizador final da app

Revogue as chaves de acesso OAuth2 associadas ao ID de um utilizador final da app específica. Este é o token associado ao ID do utilizador ao qual os tokens foram emitidos.

Por predefinição, não existe nenhum campo para o ID do utilizador final no token de acesso OAuth. Para ativar a revogação de tokens de acesso OAuth 2.0 por ID do utilizador final, tem de configurar a política OAuthv2 para incluir o ID do utilizador no token, conforme mostrado acima.

Para obter um ID do utilizador final da app, use o Método: organizations.developers.get.

Amostras

Os exemplos seguintes usam a política Revoke OAuth V2 para revogar chaves de acesso OAuth2.

ID da app de programador

Para revogar tokens de acesso por ID da app do programador, use o elemento <AppId> na sua política.

O exemplo seguinte espera encontrar o ID da app do programador do token de acesso num parâmetro de consulta com o nome app_id:

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

Dado o ID da app do programador, a política revoga o token de acesso.

Data/hora de revogação

Para revogar tokens de acesso por ID da app de programador que foram gerados antes de uma data e hora específicas, use o elemento <RevokeBeforeTimestamp> na sua política. <RevokeBeforeTimestamp> especifica uma hora de época UTC em milissegundos. Todas as chaves emitidas antes dessa hora são revogadas.

O exemplo seguinte revoga as chaves de acesso para uma app de programador criada 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> recebe um 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.

---

Referência do elemento

A referência do elemento descreve os elementos e os 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 seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de 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 é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional

Elemento <DisplayName>

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

<DisplayName>Policy Display Name</DisplayName>

Predefinição	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <AppId>

Especifica o ID da app de programador dos tokens a revogar. Transmita uma variável que contenha o ID da app ou um ID da app literal.

<AppId>appIdString</AppId>

or:

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

Predefinição	request.formparam.app_id (a x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	String
Valores válidos	Uma variável de fluxo que contém uma string de ID de app ou uma string literal.

Elemento <Cascade>

Se true e tiver um token de acesso opaco tradicional, o token de atualização e o token de acesso são revogados se <AppId> ou <EndUserId> corresponderem. Se tiver um token de acesso JWT, apenas o token de atualização emitido com o token de acesso é revogado. Por conceção, não é possível revogar as chaves de acesso JWT. Se false, apenas a chave de acesso for revogada e a chave de atualização permanecer inalterada. O mesmo comportamento aplica-se apenas aos tokens de acesso opacos. Não é possível revogar chaves de acesso JWT.

<Cascade>false<Cascade>

Predefinição	falso
Presença	Opcional
Tipo	Boolean
Valores válidos	true ou false

Elemento <EndUserId>

Especifica o ID do utilizador final da app do token a revogar. Transmita uma variável que contenha o ID do utilizador ou uma string de token literal.

<EndUserId>userIdString</EndUserId>

or:

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

Predefinição	request.formparam.enduser_id (a x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	String
Valores válidos	Uma variável de fluxo que contenha uma string de ID do utilizador ou uma string literal.

Elemento <RevokeBeforeTimestamp>

Revogue os tokens emitidos antes da data/hora. Este elemento funciona com <AppId> e <EndUserId> para lhe permitir revogar tokens antes de uma hora específica. O valor predefinido é a hora em que a política é executada.

<RevokeBeforeTimestamp>timeStampString</RevokeBeforeTimestamp>

or:

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

Predefinição	A indicação de tempo 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 contenha uma indicação de tempo ou uma indicação de tempo literal. A data/hora não pode ser posterior à atual nem anterior a 1 de janeiro de 2014.

Variáveis de fluxo

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

Referência de erro

Esta secção descreve os códigos de falha e as mensagens de erro devolvidas, bem como as variáveis de falha definidas pelo Apigee quando esta política aciona um erro. Estas informações são importantes para saber se está a desenvolver regras de falhas para tratar falhas. Para saber mais, consulte o artigo O que precisa de saber acerca dos erros de políticas e o artigo Processamento de falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada. Os nomes dos erros apresentados abaixo são as strings que são atribuídas à variável fault.name quando ocorre um erro. Consulte a secção de variáveis de falha abaixo para ver mais detalhes.

Código de falha	Estado de HTTP	Causa
steps.oauth.v2.InvalidFutureTimestamp	500	A data/hora não pode ser posterior à atual.
steps.oauth.v2.InvalidEarlyTimestamp	500	A data/hora não pode ser anterior a 1 de janeiro de 2014.
steps.oauth.v2.InvalidTimestamp	500	A data/hora é inválida.
steps.oauth.v2.EmptyAppAndEndUserId	500	Os campos AppdId e EndUserId não podem estar vazios.

Erros de implementação

Consulte a mensagem comunicada na IU para obter informações sobre erros de implementação.

Variáveis de falha

Estas variáveis são definidas quando esta política aciona um erro no tempo de execução.

Nota: pode usar estas variáveis para criar condições de regras de falhas. Para mais informações, consulte o artigo O que precisa de saber acerca dos erros de políticas.

Variáveis	Onde	Exemplo
fault.name="fault_name"	fault_name é o nome da falha, conforme indicado na tabela Erros de tempo 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 especificado pelo utilizador da política que gerou a falha.	oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause	policy_name é o nome especificado pelo utilizador da política 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>

Tópicos relacionados

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