Política GetOAuthV2Info

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

Confira a documentação da Apigee Edge.

No momento, 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.

O que

Recebe atributos de tokens de acesso, tokens de atualização, códigos de autorização e atributos de app cliente, além de preencher variáveis com os valores desses atributos.

Essa política é útil quando você precisa configurar o comportamento dinâmico e condicional com base em um valor em um token ou código de autenticação. Sempre que a validação de token ocorre, as variáveis são preenchidas automaticamente com os valores dos atributos do token. No entanto, se a validação de token não tiver ocorrido, você poderá usar esse recurso para preencher explicitamente as variáveis com os valores do atributo de um token. Consulte também Como personalizar tokens e códigos de autorização.

Um token de acesso que você passa para esta política precisa ser válido ou a política gerará um erro invalid_access_token.

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.

OBSERVAÇÃO

O caminho do recurso usado para chamar um proxy com essa política precisa ser incluído no produto usado para gerar o token original. Em outras palavras, se você chamar o proxy com o caminho /tokeninfo, o caminho do recurso /tokeninfo precisará ser incluído no produto que foi usado para gerar o token. Caso contrário, você receberá um erro InvalidAPICallAsNoApiProductMatchFound.

Para ver mais informações, consulte GetOAuthV2Info falha se o token gerado usando produtos com caminhos de recursos na Comunidade Apigee.

Amostras

Os exemplos a seguir usam a política Get OAuth V2 Info para recuperar informações sobre vários componentes do fluxo de trabalho do OAuth2 e acessar essas informações no código.

Token de acesso

Para conseguir uma referência a um token de acesso, use o elemento <AccessToken> na política.

O exemplo a seguir espera encontrar o token de acesso em um parâmetro de consulta chamado "access_token" (você decide os detalhes reais da implementação):

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

Com o token de acesso, a política procura o perfil do token e preenche um conjunto de variáveis com os dados do perfil.

Em seguida, acesse as variáveis usando JavaScript ou outros meios. O exemplo a seguir recupera os escopos associados ao token de acesso usando JavaScript:

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

Observe que para acessar essas variáveis no código, você precisa prefixar elas com "oauthv2accesstoken". Para ver uma lista completa de variáveis disponíveis por meio do token de acesso, consulte Variáveis de token de acesso.

Código de autenticação

Para ver os atributos do código de autorização, use o elemento <AuthorizationCode> na política.

O exemplo a seguir espera encontrar o token de acesso em um parâmetro de formulário chamado "code" (você decide os detalhes reais da implementação):

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

Dado o código de autenticação, a política procura as informações do código e preenche um conjunto de variáveis com os dados do código de autenticação.

Em seguida, acesse as variáveis usando JavaScript ou outros meios. O exemplo a seguir recupera um atributo personalizado associado ao código de autorização usando JavaScript:

var attr = context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

Observe que para acessar essas variáveis no código, é preciso prefixá-las com "oauthv2authcode". Para uma lista completa de variáveis disponíveis por meio do código de autenticação, consulte Variáveis de código de autorização.

Token de atualização.

Para receber atributos de token de atualização, use o elemento <RefreshToken> na política.

O exemplo a seguir espera encontrar o token de acesso em um parâmetro de consulta chamado "refresh_token".(você decide os detalhes reais da implementação):

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

Com o token de atualização, a política procura as informações do token de atualização e preenche um conjunto de variáveis com os dados do token de atualização.

É possível acessar essas variáveis usando JavaScript ou outros meios. O exemplo a seguir recupera um atributo personalizado associado ao token de atualização usando JavaScript:

var attr = context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

Observe que para acessar as variáveis no código, insira o prefixo "oauthv2refreshtoken". Para ver uma lista completa de variáveis disponíveis por meio do token de atualização, consulte Atualizar variáveis de token.

Estático

Em alguns casos raros, talvez seja necessário receber o perfil de um token configurado estaticamente (que não seja acessível por meio de uma variável). Você pode fazer isso fornecendo o valor do token de acesso como um elemento.

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

É possível fazer isso com todos os outros tipos de token (ID do cliente, código de autorização e tokens de atualização).

ID do cliente

Este exemplo mostra como recuperar informações sobre o aplicativo cliente usando o ID do cliente. Após a execução, a política preenche um conjunto de variáveis com informações do cliente. Nesse caso, a política espera encontrar o ID do cliente em um parâmetro de consulta chamado client_id. Com o ID do cliente, a política procura o perfil do cliente e preenche um conjunto de variáveis com os dados do perfil. As variáveis terão o prefixo oauthv2client. .

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

Em seguida, acesse as variáveis usando JavaScript ou outros meios. Por exemplo, para receber o nome do aplicativo de desenvolvedor e o e-mail do desenvolvedor associados ao aplicativo cliente usando JavaScript:

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

---

Referência de elemento

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

Atributos <GetOAuthV2Info>

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

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

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. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual	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
async	Esse atributo está obsoleto.	falso	Descontinuado

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.
Presença	Opcional
Tipo	String

Elemento <AccessToken>

Recupera o perfil de um token de acesso. Você transmite uma variável que contém a string do token de acesso ou uma string de token literal (caso raro). Neste exemplo, o token de acesso é recuperado de um parâmetro de consulta transmitido em uma solicitação. Use o elemento <IgnoreAccessTokenStatus> se quiser retornar informações para um token revogado ou expirado.

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

Padrão:	request.formparam.access_token (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 token de acesso ou uma string literal.

Elemento <AuthorizationCode>

Recupera o perfil para um código de autorização. Você transmite uma variável que contém a string do código de autenticação ou uma string de token literal (caso raro). Neste exemplo, o código de autenticação é recuperado de um parâmetro de consulta transmitido em uma solicitação. Para ver uma lista de variáveis preenchidas por essa operação, consulte "Variáveis de fluxo".

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

Padrão:	request.formparam.access_token (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 código de autenticação ou uma string literal.

Elemento <ClientId>

Recupera informações relacionadas a um ID do cliente. Neste exemplo, o ID do cliente é recuperado de um parâmetro de consulta passado em uma solicitação. Para ver uma lista de variáveis preenchidas por essa operação, consulte "Variáveis de fluxo".

<ClientId ref="request.queryparam.client_id"></ClientId>

Padrão:	request.formparam.access_token (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 código de autenticação ou uma string literal.

Elemento <IgnoreAccessTokenStatus>

Retorna as informações do token mesmo que o token tenha expirado ou revogado. Esse elemento só pode ser usado com tokens de acesso. Por padrão, as informações de outras entidades, como tokens de atualização e códigos de autorização, são retornadas, independentemente do status delas.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Padrão:	false
Presença:	Opcional
Tipo:	Booleano
Valores válidos:	Verdadeiro ou falso?

Elemento <RefreshToken>

Recupera o perfil de um token de atualização. Você passa uma variável que contém a string de token de atualização ou uma string de token literal (caso raro). Neste exemplo, o token de atualização é recuperado de um parâmetro de consulta transmitido em uma solicitação. Para ver uma lista de variáveis preenchidas por essa operação, consulte "Variáveis de fluxo".

Observação: esse elemento funciona da mesma forma se você usa um token de atualização emitido com um token de acesso JWT ou com um token de acesso opaco tradicional.

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

Padrão:	request.formparam.access_token (um x-www-form-urlencoded e especificado no corpo da solicitação)
Presença:	Opcional
Tipo:	String
Valores válidos:	Pode ser uma variável de fluxo contendo uma string de token de atualização ou uma string literal.

Variáveis de fluxo

A política GetOAuthV2Info preenche essas variáveis e normalmente é usada nos casos em que você precisa dos dados do perfil, mas lá uma concessão ou validação ainda não ocorreu. .

Variáveis de ID do cliente

Essas variáveis são preenchidas quando o elemento ClientId é definido:

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

Acessar variáveis de token

Essas variáveis são preenchidas quando o elemento AccessToken é definido:

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Variáveis de código de autorização

Essas variáveis são preenchidas quando o elemento AuthorizationCode é definido:

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope       
oauthv2authcode.{policy_name}.redirect_uri 
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

Atualizar variáveis de token

Essas variáveis são preenchidas quando o elemento RefreshToken é definido:

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

Esquema

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.

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.access_token_expired	500	O token de acesso enviado para a política expirou.
steps.oauth.v2.authorization_code_expired	500	O código de autorização enviado para a política expirou.
steps.oauth.v2.invalid_access_token	500	O token de acesso enviado para a política é inválido.
steps.oauth.v2.invalid_client-invalid_client_id	500	O ID do cliente enviado para a política é inválido.
steps.oauth.v2.invalid_refresh_token	500	O token de atualização enviado para a política é inválido.
steps.oauth.v2.invalid_request-authorization_code_invalid	500	O código de autorização enviado para a política é inválido.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	Consulte A verificação do token de acesso do Oauth2.0 gera um erro "Chamada de API inválida como nenhuma correspondência de apiproduct foi encontrada" para mais informações sobre como solucionar este erro.
steps.oauth.v2.refresh_token_expired	500	O token de atualização enviado para a política expirou.

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":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

Exemplo de regra de falha

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

Temas relacionados

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