Esta página foi traduzida pela API Cloud Translation.

Política GetOAuthV2Info

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

Veja a documentação do Apigee Edge.

O quê

Obtém atributos de chaves de acesso, tokens de atualização, códigos de autorização e atributos da app cliente, e preenche as variáveis com os valores desses atributos.

Esta política é útil quando precisa de configurar um comportamento dinâmico e condicional com base num valor num token ou num código de autorização. Sempre que ocorre a validação de tokens, as variáveis são preenchidas automaticamente com os valores dos atributos dos tokens. No entanto, nos casos em que a validação de tokens não ocorreu, pode usar esta funcionalidade para preencher explicitamente as variáveis com os valores de atributos de um token. Consulte também Personalizar tokens e códigos de autorização.

Um token de acesso que transmite a esta política tem de ser válido. Caso contrário, a política gera um erro invalid_access_token.

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.

Amostras

Os exemplos seguintes usam a política Get OAuth V2 Info para obter informações sobre vários componentes do fluxo de trabalho OAuth2 e, em seguida, aceder a essas informações no código.

Chave de acesso

Para obter uma referência a uma chave de acesso, use o elemento <AccessToken> na sua política.

O exemplo seguinte espera encontrar o token de acesso num parâmetro de consulta com o nome "access_token" (os detalhes de implementação reais dependem de si):

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

Dado 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, pode aceder às variáveis através de JavaScript ou de outro meio. O exemplo seguinte obtém os âmbitos associados ao token de acesso através de JavaScript:

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

Tenha em atenção que, para aceder a essas variáveis no código, tem de precedê-las com "oauthv2accesstoken". Para ver uma lista completa das variáveis disponíveis através do token de acesso, consulte o artigo Variáveis do token de acesso.

Código de autorização

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

O exemplo seguinte espera encontrar o token de acesso num parâmetro de formulário denominado "code" (os detalhes de implementação reais dependem de si):

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

Dado o código de autorizaçã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 autorização.

Em seguida, pode aceder às variáveis através de JavaScript ou de outro meio. O exemplo seguinte obtém um atributo personalizado associado ao código de autorização através de JavaScript:

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

Tenha em atenção que, para aceder a essas variáveis no código, tem de precedê-las com "oauthv2authcode". Para ver uma lista completa das variáveis disponíveis através do código de autorização, consulte o artigo Variáveis do código de autorização.

Símbolo de atualização

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

O exemplo seguinte espera encontrar o token de acesso num parâmetro de consulta com o nome "refresh_token" (os detalhes de implementação reais dependem de si):

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

Dado 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.

Em seguida, pode aceder a essas variáveis através de JavaScript ou de outro meio. O exemplo seguinte obtém um atributo personalizado associado ao token de atualização através de JavaScript:

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

Tenha em atenção que, para aceder às variáveis no código, tem de adicionar o prefixo "oauthv2refreshtoken". Para ver uma lista completa das variáveis disponíveis através do token de atualização, consulte o artigo Variáveis do token de atualização.

Estático

Em alguns casos raros, pode ter de obter o perfil de um token configurado estaticamente (um que não seja acessível através de uma variável). Pode fazê-lo fornecendo o valor do token de acesso como um elemento.

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

Também pode fazê-lo com todos os outros tipos de tokens (ID de cliente, código de autorização e tokens de atualização).

ID do cliente

Este exemplo mostra como obter informações sobre a app cliente através do ID de cliente. Após a execução, a política preenche um conjunto de variáveis com informações do cliente. Neste caso, a política espera encontrar o ID de cliente num parâmetro de consulta denominado client_id. Dado 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 vão ter o prefixo oauthv2client.

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

Em seguida, pode aceder às variáveis através de JavaScript ou de outro meio. Por exemplo, para obter o nome da app do programador e o email do programador associados à app cliente através de JavaScript:

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

Referência do elemento

A referência de elementos descreve os elementos e os 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 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. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar 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 é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
`async`	Este atributo foi descontinuado.	falso	Descontinuado

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

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

N/A

Se omitir este elemento, é usado o valor do atributo name da política.

Presença Opcional

Tipo String

Elemento <AccessToken>

Obtém o perfil de um token de acesso. Transmite uma variável que contém a string do token de acesso ou uma string do token literal (caso raro). Neste exemplo, o token de acesso é obtido a partir de um parâmetro de consulta transmitido num pedido. Use o elemento <IgnoreAccessTokenStatus> se quiser devolver informações para um token revogado ou expirado.

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

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

Elemento <AuthorizationCode>

Obtém o perfil de um código de autorização. Transmite uma variável que contém a string do código de autorização ou uma string de token literal (caso raro). Neste exemplo, o código de autorização é obtido a partir de um parâmetro de consulta transmitido num pedido. Para ver uma lista das variáveis preenchidas por esta operação, consulte "Variáveis de fluxo".

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

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

Elemento <ClientId>

Obtém informações relacionadas com um ID de cliente. Neste exemplo, o ID de cliente é obtido a partir de um parâmetro de consulta transmitido num pedido. Para ver uma lista das variáveis preenchidas por esta operação, consulte "Variáveis de fluxo".

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

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

Elemento <IgnoreAccessTokenStatus>

Devolve as informações do token, mesmo que o token esteja expirado ou revogado. Este elemento só pode ser usado com tokens de acesso. As informações para outras entidades, como os tokens de atualização e os códigos de autorização, são devolvidas por predefinição, independentemente do respetivo estado.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

Predefinição:	falso
Presença:	Opcional
Tipo:	Boolean
Valores válidos:	verdadeiro ou falso

Elemento <RefreshToken>

Obtém o perfil de um token de atualização. Transmite uma variável que contém a string do token de atualização ou uma string do token literal (caso raro). Neste exemplo, o token de atualização é obtido a partir de um parâmetro de consulta transmitido num pedido. Para ver uma lista das variáveis preenchidas por esta operação, consulte "Variáveis de fluxo".

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

Predefinição:	request.formparam.access_token (um 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 token de atualização ou uma string literal.

Variáveis de fluxo

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

Variáveis de ID de cliente

Estas variáveis são preenchidas quando o elemento ClientId está 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}

Variáveis de token de acesso

Estas variáveis são preenchidas quando o elemento AccessToken está 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 do código de autorização

Estas variáveis são preenchidas quando o elemento AuthorizationCode está 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}

Atualize as variáveis do token

Estas variáveis são preenchidas quando o elemento RefreshToken está 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íticas estão disponíveis no GitHub.

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.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 o artigo A validação do token de acesso do Oauth2.0 gera o erro "Invalid API call as no apiproduct match found" para obter informações sobre a resolução de problemas deste erro.
`steps.oauth.v2.refresh_token_expired`	`500`	O token de atualização enviado para a política expirou.

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.

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":"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>