Política OAuthV2

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

Veja a documentação do Apigee Edge.

O quê

O OAuthV2 é uma política multifacetada para realizar operações do tipo de concessão OAuth 2.0. Esta é a política principal usada para configurar os pontos finais do OAuth 2.0 no Apigee.

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.

Para saber mais sobre o OAuth no Apigee, consulte a página inicial do OAuth. Inclui links para recursos, exemplos, vídeos e muito mais.

Sugestão: consulte a política VerifyIAM para ver uma política padrão que fornece um método integrado do Google Cloud IAM de gestão da autenticação e autorização num proxy.

Exemplos

VerifyAccessToken

VerifyAccessToken

Esta configuração da política OAuthV2 (com a operação VerifyAccessToken) verifica se um token de acesso enviado para o Apigee é válido. Quando esta operação de política é acionada, o Apigee procura um token de acesso válido no pedido. Se o token de acesso for válido, o pedido pode prosseguir. Se for inválido, todo o processamento é interrompido e é devolvido um erro na resposta.

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

Nota: apenas são suportados tokens de portador OAuth 2.0. Outros tipos de tokens, como tokens de código de autenticação de mensagens (MAC), não são suportados.

Uma aplicação cliente tem de enviar um pedido com um token. Por exemplo, usando o curl, pode ser:

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

Onde API_ENDPOINT é o domínio usado para aceder às suas APIs, conforme configurado no seu sistema Apigee.

Por predefinição, a política OAuthV2 extrai o token de acesso do cabeçalho Authorization, removendo o prefixo Bearer. Pode alterar este comportamento predefinido com o elemento de configuração AccessToken.

GenerateAccessToken

Gerar tokens de acesso

Para ver exemplos que mostram como pedir chaves de acesso para cada um dos tipos de concessão suportados, consulte o artigo Obtenha tokens OAuth 2.0. O tópico inclui exemplos destas operações:

• Código de autorização
• Credenciais de cliente
• Implícito
• Palavra-passe

Nota: com a operação GenerateAccessToken, a política OAuthV2 pode devolver uma resposta que não esteja totalmente em conformidade com as especificações de OAuth 2.0 relacionadas. Por exemplo, a propriedade token_type na resposta do token pode não estar em conformidade. Para ver detalhes sobre este e outros elementos de resposta não conformes possíveis, consulte o comportamento em conformidade com a RFC.

GenerateAuthorizationCode

Gere o código de autorização

Para ver exemplos que mostram como pedir códigos de autorização, consulte o artigo Pedir um código de autorização.

RefreshAccessToken

Atualize uma chave de acesso

Para ver exemplos que mostram como pedir chaves de acesso através de um símbolo de atualização, consulte o artigo Atualizar uma chave de acesso.

Tokens de acesso JWT

Tokens de acesso JWT

Para ver exemplos que mostram como gerar, validar e atualizar chaves de acesso JWT, consulte o artigo Usar chaves de acesso JWT.

Token de fluxo de resposta

Gere um token de acesso no fluxo de resposta

Por vezes, pode ter de gerar uma chave de acesso no fluxo de resposta. Por exemplo, pode fazê-lo em resposta a alguma validação personalizada feita num serviço de back-end. Neste exemplo, o exemplo de utilização requer uma chave de acesso e uma chave de atualização, o que exclui o tipo de concessão implícita. Neste caso, vamos usar o tipo de autorização de palavra-passe para gerar o token. Como vai ver, o truque para que isto funcione é transmitir um cabeçalho de pedido de autorização com uma política de JavaScript.

Primeiro, vamos analisar a política de exemplo:

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

Se colocar esta política no fluxo de resposta, vai falhar com um erro 401 UnAuthorized, mesmo que os parâmetros de início de sessão corretos sejam especificados na política. Para resolver este problema, tem de definir um cabeçalho de pedido de autorização.

O cabeçalho Authorization tem de conter um esquema de acesso básico com o client_id:client_secret codificado em Base64.

Pode adicionar este cabeçalho com uma política de JavaScript colocada imediatamente antes da política OAuthV2, como neste exemplo. As variáveis de contexto "local_clientid" e "local_secret" têm de ser definidas previamente e estar disponíveis no fluxo:

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

Aviso: as políticas VerifyAPIKey e OAuthV2 podem registar um aumento das latências p90+ em condições específicas. Este comportamento é normalmente observado quando a taxa de consultas por segundo (QPS) é muito baixa (taxa de um único dígito) e os processadores de mensagens (MPs) estão excessivamente aprovisionados. A latência elevada nestes cenários é atribuída principalmente à utilização ineficiente da cache.

Veja também o artigo Codificar credenciais de autenticação básica.

Referência do elemento

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

Nota: a forma como configura esta política e os elementos que tem de especificar dependem da operação que quer que a política execute. Por exemplo, se estiver a implementar o tipo de concessão de código de autorização, precisa de quatro políticas OAuthV2 separadas para realizar a geração de código de autorização, a geração de código de acesso, a validação de código de acesso e a geração de token de atualização. Esta referência apresenta todos os elementos que podem ser usados com esta política.

Se quiser ver configurações para exemplos de utilização de tipos de autorização específicos, consulte a página inicial do OAuth para ver uma lista de implementações de tipos de autorização.

A política de exemplo apresentada abaixo é uma de muitas configurações possíveis. Este exemplo mostra uma política OAuthV2 configurada para a operação GenerateAccessToken. Inclui elementos obrigatórios e opcionais. Consulte as descrições dos elementos nesta secção para ver detalhes.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

Atributos <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

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	N/A Se omitir este elemento, é usado o valor do atributo name da política.
Presença	Opcional
Tipo	String

Elemento <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

Por predefinição, quando o Operation está VerifyAccessToken, a política espera que o token de acesso seja enviado no cabeçalho Authorization como um token de portador, ou seja, com o prefixo "Bearer", seguido de um espaço em branco. Pode alterar essa predefinição através deste elemento, especificando o nome de uma variável que contém o token de acesso a validar. Quando usa este elemento, a política, por predefinição, não procura um prefixo no conteúdo da variável. Se quiser especificar que a política deve procurar um prefixo, use também o elemento AccessTokenPrefix.

Exemplos:

• Quando a configuração da política é:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.header.access_token</AccessToken>
    </OAuthV2>

  Para transmitir o token através do curl, pode usar:

    curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

• Quando a configuração da política é:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.queryparam.token</AccessToken>
    </OAuthV2>

  Para transmitir o token através do curl, pode usar:

    curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

Onde API_ENDPOINT é o domínio usado para aceder às suas APIs, conforme configurado no seu sistema Apigee.

Predefinição	N/A
Presença	Opcional
Tipo	String
Valores válidos	qualquer nome de variável
Usado com operações	VerifyAccessToken

Elemento <AccessTokenPrefix>

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

Por predefinição, quando o Operation está VerifyAccessToken, a política espera que o token de acesso seja enviado no cabeçalho Authorization como um token de portador, ou seja, com o prefixo "Bearer", seguido de um espaço em branco. Se usar o elemento AccessToken para especificar uma localização diferente para o token de acesso recebido, também pode usar este elemento, AccessTokenPrefix, para especificar um prefixo diferente e não padrão.

Por exemplo, se especificar:

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

Em seguida, a política extrai o token de acesso de entrada do cabeçalho do pedido token, da seguinte forma: se o cabeçalho começar com a palavra "KEY" seguida de um espaço, a política remove esse prefixo e espaço e interpreta o valor restante como o token de acesso. Se o prefixo especificado não estiver presente no cabeçalho, a política vai gerar uma falha.

Se especificar o elemento AccessToken e não especificar o elemento AccessTokenPrefix, a política interpreta todo o valor da variável especificada no elemento AccessToken como o token de acesso.

Este elemento só é eficaz quando o elemento AccessToken também é usado.

Predefinição	-none-
Presença	Opcional
Tipo	String
Valores válidos	qualquer string
Usado com operações	VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica o algoritmo de encriptação usado para assinar um token de acesso JWT. Os algoritmos RSA (RS*) usam um par de chaves pública/secreta, enquanto os algoritmos HMAC (HS*) usam um segredo partilhado. Este elemento é obrigatório para as operações GenerateJWTAccessToken, VerifyJWTAccessToken e RefreshJWTAccessToken.

Predefinição	N/A
Presença	Obrigatório quando usar as operações GenerateJWTAccessToken, VerifyJWTAccessToken e RefreshJWTAccessToken.
Tipo	String
Valores válidos	HS256, HS384, HS512, RS256, RS384 e RS512

Elemento <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Nos casos em que o ID do utilizador final da app tem de ser enviado para o servidor de autorização, este elemento permite-lhe especificar onde o Apigee deve procurar o ID do utilizador final. Por exemplo, pode ser enviado como um parâmetro de consulta ou num cabeçalho HTTP.

Por exemplo, request.queryparam.app_enduser indica que o AppEndUser deve estar presente como um parâmetro de consulta, como, por exemplo, ?app_enduser=[e-mail]. Para exigir o AppEndUser num cabeçalho HTTP, por exemplo, defina este valor como request.header.app_enduser.

A disponibilização desta definição permite-lhe incluir um ID do utilizador final da app no token de acesso. Esta funcionalidade é útil se quiser poder obter ou revogar tokens de acesso OAuth 2.0 por ID do utilizador final. Para mais informações, consulte o artigo Ative a obtenção e a revogação de tokens de acesso OAuth 2.0 por ID do utilizador final, ID da app ou ambos.

Predefinição	N/A
Presença	Opcional
Tipo	String
Valores válidos	Qualquer variável de fluxo acessível à política no tempo de execução.
Usado com tipos de concessão	authorization_code implícita palavra-passe client_credentials

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Use este elemento para adicionar atributos personalizados a um token de acesso ou a um código de autorização. Por exemplo, pode querer incorporar um ID do utilizador ou um identificador de sessão num token de acesso que possa ser extraído e verificado no tempo de execução.

Este elemento permite especificar um valor numa variável de fluxo ou a partir de uma string literal. Se especificar uma variável e uma string, é usado o valor especificado na variável de fluxo. Se não for possível resolver a variável, a string é a predefinição.

Para mais informações sobre a utilização deste elemento, consulte o artigo Personalizar tokens e códigos de autorização.

Notas:

Pode criar até 18 atributos personalizados.

Se adicionar atributos personalizados a um código de autorização, esses atributos são herdados pelo token de acesso gerado a partir desse código.

Apresentar ou ocultar atributos personalizados na resposta

Tenha em atenção que, se definir o elemento GenerateResponse desta política como verdadeiro, a representação JSON completa do token é devolvida na resposta, incluindo quaisquer atributos personalizados que definir. Em alguns casos, pode querer ocultar alguns ou todos os seus atributos personalizados na resposta para que não fiquem visíveis para as apps cliente.

Por predefinição, os atributos personalizados aparecem na resposta. Se quiser ocultá-los, pode definir o parâmetro display como false. Por exemplo:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

O valor do atributo display não é mantido. Suponhamos que gera um token de acesso com atributos personalizados que quer ocultar na resposta gerada. A definição de display=false cumpre esse objetivo. No entanto, se for gerada uma nova chave de acesso posteriormente através de uma chave de atualização, os atributos personalizados originais da chave de acesso são apresentados na resposta da chave de atualização. Isto deve-se ao facto de o Apigee não se lembrar de que o atributo display foi originalmente definido como false na política de geração de tokens de acesso. O atributo personalizado faz simplesmente parte dos metadados do token de acesso.

Vai observar o mesmo comportamento se adicionar atributos personalizados a um código de autorização. Quando é gerado um token de acesso através desse código, esses atributos personalizados são apresentados na resposta do token de acesso. Mais uma vez, este pode não ser o comportamento pretendido.

Para ocultar atributos personalizados nestes casos, tem as seguintes opções:

• Reponha explicitamente os atributos personalizados na política de tokens de atualização e defina a respetiva apresentação como falsa. Neste caso, pode ter de obter os valores personalizados originais do token de acesso original através da política GetOAuthV2Info.
• Use uma política de JavaScript de pós-processamento para extrair manualmente quaisquer atributos personalizados que não queira ver na resposta.

Consulte também o artigo Personalizar tokens e códigos de autorização.

Predefinição	N/A
Presença	Opcional
Valores válidos	name: o nome do atributo ref: o valor do atributo. Pode ser proveniente de uma variável de fluxo. display - (Opcional) Permite especificar se os atributos personalizados aparecem ou não na resposta. Se true, os atributos personalizados aparecem na resposta (se GenerateResponse também estiver ativado). Se false, os atributos personalizados não são incluídos na resposta. O valor predefinido é true. Consulte o artigo Apresentar ou ocultar atributos personalizados na resposta.
Usado com tipos de concessão	authorization_code implícita palavra-passe client_credentials refresh_token Também pode ser usado com a operação GenerateAuthorizationCode.

Elemento <CacheExpiryInSeconds>

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

Este elemento só pode ser usado com a operação VerifyAccessToken. Especifica o tempo de vida (TTL) na cache de tokens de acesso para a execução de políticas específica. A primeira vez que o Apigee valida uma chave de acesso OAuth 2, tem de obter a chave de acesso a partir de um armazenamento persistente. Esta é uma operação relativamente dispendiosa, pelo que o Apigee armazena em cache o resultado da pesquisa de tokens, incluindo o estado do token, a lista de produtos para os quais o token é válido e quaisquer atributos personalizados anexados ao token. As invocações subsequentes de OAuthV2/VerifyAccessToken até o TTL expirar vão ler o resultado em cache na memória, o que significa que a validação de tokens vai ser muito mais rápida.

O TTL predefinido para a cache de tokens de acesso é de 180 segundos. Este elemento permite-lhe reduzir o TTL, trocando o desempenho pela correção. Um cenário em que isto faria sentido é se, por vezes, revogar tokens e quiser reduzir o período durante o qual o Apigee continua a tratar os tokens revogados como válidos.

O intervalo suportado é entre 1 e 180 segundos. Pode fornecer uma variável de fluxo e um valor predefinido. Se fornecer uma variável de fluxo e esta contiver um valor numérico, tem precedência sobre o valor predefinido especificado.

Nota: o desempenho diminui quando usa um número inferior para o prazo de validade da cache.

Predefinição	N/A Se omitir este elemento, o período de validade predefinido do token de acesso em cache é de 180 segundos.
Presença	Opcional
Tipo	Número inteiro
Valores válidos	Qualquer número inteiro positivo que não seja zero. Especifica o tempo de validade em segundos.
Usado com operações	VerifyAccessToken

Atributos

A tabela seguinte descreve os atributos do elemento <CacheExpiryInSeconds>

Atributo	Descrição	Predefinição	Presença
ref	Uma referência à variável de fluxo que contém o valor da expiração da cache, expresso em segundos. Se for fornecido, o valor da variável de fluxo tem precedência sobre o valor predefinido especificado.	N/A	Opcional

Elemento <ClientId>

<ClientId>request.formparam.client_id</ClientId>

Em vários casos, a app cliente tem de enviar o ID de cliente para o servidor de autorizações. Este elemento especifica que o Apigee deve procurar o ID do cliente na variável de fluxo request.formparam.client_id. A definição de ClientId para qualquer outra variável não é suportada. Consulte também o artigo Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.client_id (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	String
Valores válidos	A variável de fluxo: request.formparam.client_id
Usado com tipos de concessão	authorization_code palavra-passe implícita client_credentials Também pode ser usado com a operação GenerateAuthorizationCode.

Elemento <Code>

<Code>request.queryparam.code</Code>

No fluxo do tipo de concessão de autorização, o cliente tem de enviar um código de autorização para o servidor de autorização (Apigee). Este elemento permite-lhe especificar onde o Apigee deve procurar o código de autorização. Por exemplo, pode ser enviado como um parâmetro de consulta, um cabeçalho HTTP ou um parâmetro de formulário (predefinição).

A variável request.queryparam.auth_code indica que o código de autorização deve estar presente como um parâmetro de consulta, como, por exemplo, ?auth_code=AfGlvs9. Para exigir o código de autorização num cabeçalho HTTP, por exemplo, defina este valor como request.header.auth_code. Consulte também: Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.code (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	opcional
Tipo	String
Valores válidos	Qualquer variável de fluxo acessível à política no tempo de execução
Usado com tipos de concessão	authorization_code

Elemento<ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

Aplica o tempo de validade das chaves de acesso e dos códigos de autorização em milissegundos. (Para tokens de atualização, use <RefreshTokenExpiresIn>.) O valor do tempo de expiração é um valor gerado pelo sistema mais o valor <ExpiresIn>. Se <ExpiresIn> não for especificado, o sistema aplica um valor predefinido configurado ao nível do sistema.

O tempo de expiração também pode ser definido no tempo de execução através de um valor predefinido codificado ou fazendo referência a uma variável de fluxo. Por exemplo, pode armazenar um valor de expiração do token num mapa de chave-valor, obtê-lo, atribuí-lo a uma variável e fazer referência ao mesmo na política. Por exemplo, kvm.oauth.expires_in.

O Apigee mantém as seguintes entidades na cache durante um mínimo de 180 segundos após o acesso às entidades.

• Tokens de acesso OAuth. Isto significa que o elemento ExpiresIn na política OAuth v2 não vai poder fazer expirar uma chave de acesso em menos de 180 segundos.
• Entidades do Key Management Service (KMS) (Apps, Developers e API Products).
• Atributos personalizados em tokens OAuth e entidades KMS.

A stanza seguinte especifica uma variável de fluxo e também um valor predefinido. Tenha em atenção que o valor da variável de fluxo tem precedência sobre o valor predefinido especificado.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

O Apigee não suporta uma forma de forçar a expiração de um token depois de ter sido criado. Se precisar de forçar a expiração do token (por exemplo, com base numa condição), encontra uma possível solução descrita nesta publicação da comunidade do Apigee.

Por predefinição, os tokens de acesso expirados são eliminados do sistema Apigee Apigee automaticamente 3 dias após a expiração. Veja também como eliminar tokens de acesso

Predefinição	Se não for especificado, o sistema aplica um valor predefinido configurado ao nível do sistema.
Presença	Opcional
Tipo	Número inteiro
Valores válidos	Qualquer número inteiro positivo diferente de zero. Especifique o tempo de validade em milissegundos. Embora o valor deste elemento esteja em milissegundos, o valor definido na propriedade expires_in do token e na variável de fluxo expires_in é expresso em segundos.
Usado com tipos de concessão	authorization_code implícita palavra-passe client_credentials refresh_token Também usado com a operação GenerateAuthorizationCode.

Elemento <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Indica ao Apigee onde encontrar um token de acesso externo (um token de acesso não gerado pelo Apigee).

A variável request.queryparam.external_access_token indica que o token de acesso externo deve estar presente como um parâmetro de consulta, como, por exemplo, ?external_access_token=12345678. Para exigir o token de acesso externo num cabeçalho HTTP, por exemplo, defina este valor como request.header.external_access_token. Consulte também o artigo Usar tokens OAuth de terceiros.

Elemento <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Se este elemento for falso ou não estiver presente, o Apigee valida o client_id e o client_secret normalmente em relação ao arquivo de autorizações do Apigee. Use este elemento quando quiser trabalhar com tokens OAuth de terceiros. Para ver detalhes sobre a utilização deste elemento, consulte o artigo Usar tokens OAuth de terceiros.

Predefinição	falso
Presença	Opcional
Tipo	Booleano
Valores válidos	verdadeiro ou falso
Usado com tipos de concessão	authorization_code palavra-passe client_credentials

Elemento <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Indica ao Apigee onde encontrar um código de autorização externo (um código de autorização não gerado pelo Apigee).

A variável request.queryparam.external_auth_code indica que o código de autorização externo deve estar presente como um parâmetro de consulta, como, por exemplo, ?external_auth_code=12345678. Para exigir o código de autorização externa num cabeçalho HTTP, por exemplo, defina este valor como request.header.external_auth_code. Consulte também o artigo Usar tokens OAuth de terceiros.

Elemento <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Indica ao Apigee onde encontrar um símbolo de atualização externo (um símbolo de atualização não gerado pelo Apigee).

A variável request.queryparam.external_refresh_token indica que o token de atualização externo deve estar presente como um parâmetro de consulta, como, por exemplo, ?external_refresh_token=12345678. Para exigir o token de atualização externo num cabeçalho HTTP, por exemplo, defina este valor como request.header.external_refresh_token. Consulte também o artigo Usar tokens OAuth de terceiros.

Elemento <GenerateResponse>

<GenerateResponse enabled='true'/>

Se for definido como true ou se o atributo enabled for omitido, a política gera e devolve uma resposta. Por exemplo, para GenerateAccessToken, a resposta pode ser semelhante a:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "[e-mail]",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Se for definido como false ou se o elemento <GenerateResponse> for omitido, não é enviada nenhuma resposta. Em alternativa, um conjunto de variáveis de fluxo é preenchido com valores relacionados com a função da política. Por exemplo, uma variável de fluxo denominada oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code é preenchida com o código de autorização recém-gerado. Tenha em atenção que expires_in é expresso em segundos na resposta.

Predefinição	verdadeiro
Presença	Opcional
Tipo	de string
Valores válidos	verdadeiro ou falso
Usado com tipos de concessão	implícita palavra-passe client_credentials refresh_token Também pode ser usado com a operação GenerateAuthorizationCode.

Elemento <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Se for definido como true, a política gera e devolve uma resposta se o atributo ContinueOnError estiver definido como verdadeiro. Se false (a predefinição), não é enviada nenhuma resposta. Em alternativa, um conjunto de variáveis de fluxo é preenchido com valores relacionados com a função da política.

Predefinição	falso
Presença	Opcional
Tipo	de string
Valores válidos	verdadeiro ou falso
Usado com tipos de concessão	implícita palavra-passe client_credentials refresh_token Também pode ser usado com a operação GenerateAuthorizationCode.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Indica à política onde encontrar o parâmetro de tipo de autorização transmitido num pedido. De acordo com a especificação OAuth 2.0, o tipo de autorização tem de ser fornecido com pedidos de chaves de acesso e códigos de autorização. A variável pode ser um cabeçalho, um parâmetro de consulta ou um parâmetro de formulário (predefinição).

Por exemplo, request.queryparam.grant_type indica que a palavra-passe deve estar presente como um parâmetro de consulta, como, por exemplo, ?grant_type=password. Para exigir o tipo de autorização num cabeçalho HTTP, por exemplo, defina este valor como request.header.grant_type. Consulte também o artigo Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.grant_type (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	de string
Valores válidos	Uma variável, conforme explicado acima.
Usado com tipos de concessão	authorization_code palavra-passe implícita client_credentials refresh_token

Elemento <Operation>

<Operation>GenerateAuthorizationCode</Operation>

A operação OAuth 2.0 executada pela política.

Predefinição	Se <Operation> não for especificado, o Apigee analisa a lista de <SupportedGrantTypes>. Apenas as operações nesses tipos de concessão vão ser bem-sucedidas. Por outras palavras, pode omitir <Operation> se especificar um <GrantType> na lista <SupportedGrantTypes>. Se não forem especificados <Operation> nem <SupportedGrantTypes>, o tipo de autorização predefinido é authorization_code. Ou seja, os pedidos do tipo de concessão authorization_code vão ser bem-sucedidos, mas todos os outros vão falhar.
Presença	Opcional
Tipo	String
Valores válidos	GenerateAccessToken - Gera um token de acesso. Consulte também o artigo Obtenha tokens OAuth 2.0. GenerateAccessTokenImplicitGrant - Gera um token de acesso para o tipo de autorização implícito. Consulte também o artigo Obtenha tokens OAuth 2.0. GenerateAuthorizationCode – Gera um código de autorização. Usado com o tipo de concessão de código de autorização. Consulte também o artigo Obtenha tokens OAuth 2.0. RefreshAccessToken – Troque um token de atualização por um novo token de acesso. Consulte também o artigo Obtenha tokens OAuth 2.0. VerifyAccessToken - Verifica se um token de acesso enviado num pedido é válido. Consulte o exemplo VerifyAccessToken acima e o artigo Validar tokens de acesso. InvalidateToken - Revoga um token de acesso. Depois de um token ser revogado, os clientes não podem usar esse token para chamar uma API protegida. Consulte também Aprovar e revogar tokens de acesso. 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. ValidateToken - Restaura ou "aprova" um token de acesso que foi revogado anteriormente. Consulte também Aprovar e revogar tokens de acesso. Operações adicionais de tokens de acesso JWT Se preferir usar tokens de acesso JWT em vez de tokens de string opacos, as seguintes operações também estão disponíveis para gerar e validar tokens JWT. Para ver detalhes, consulte o artigo Usar operações de tokens OAuth JWT: GenerateJWTAccessToken – Gera um token de acesso com um JWT assinado. Consulte o artigo Gerar um token de acesso JWT. GenerateJWTAccessTokenImplicitGrant: gera um token de acesso com um JWT assinado para o tipo de concessão implícito. Consulte o artigo Gerar um token de acesso JWT. VerifyJWTAccessToken – Valida um token de acesso JWT assinado. Consulte também o artigo Validar um token de acesso JWT. RefreshJWTAccessToken - Troque um token de atualização por um novo token de acesso JWT. Consulte também o artigo Atualizar um token de acesso JWT.

Elemento <PassWord>

<PassWord>request.queryparam.password</PassWord>

Este elemento é usado apenas com o tipo de concessão de palavra-passe. Com o tipo de autorização de palavra-passe, as credenciais do utilizador (palavra-passe e nome de utilizador) têm de ser disponibilizadas à política OAuthV2. Os elementos <PassWord> e <UserName> são usados para especificar variáveis onde o Apigee pode encontrar estes valores. Se estes elementos não forem especificados, a política espera encontrar os valores (por predefinição) nos parâmetros do formulário denominados username e password. Se os valores não forem encontrados, a política gera um erro. Pode usar os elementos <PassWord> e <UserName> para fazer referência a qualquer variável de fluxo que contenha as credenciais.

Por exemplo, pode transmitir a palavra-passe num pedido de token através de um parâmetro de consulta e definir o elemento da seguinte forma: <PassWord>request.queryparam.password</PassWord>. Para exigir a palavra-passe num cabeçalho HTTP, defina este valor como request.header.password.

A política OAuthV2 não faz mais nada com estes valores de credenciais. O Apigee está simplesmente a verificar se estão presentes. É da responsabilidade do programador da API obter os valores pedidos e enviá-los a um fornecedor de identidade antes de a política de geração de tokens ser executada.

Consulte também o artigo Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.password (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	String
Valores válidos	Qualquer variável de fluxo disponível para a política no tempo de execução.
Usado com tipos de concessão	palavra-passe

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

Fornece a chave privada usada para validar ou assinar tokens de acesso formatados em JWT com um algoritmo RSA. Use o atributo ref para transmitir a chave numa variável de fluxo. Use apenas quando o valor do elemento Algorithm for um dos seguintes: RS256, RS384 ou RS512. Para mais informações, consulte o artigo Usar operações de tokens OAuth JWT.

Nota: para proteger segredos, é uma prática recomendada armazenar a chave num conjunto de propriedades com âmbito do ambiente ou num mapa de valores-chave (KVM) com âmbito do ambiente. Consulte também Aceda aos valores definidos da propriedade e Use mapas de valores-chave.

Predefinição	N/A
Presença	Obrigatório quando o valor do elemento Algorithm é um dos seguintes: HS256, HS384 ou HS512.
Tipo	String
Valores válidos	Uma variável de fluxo que contém uma string que representa um valor de chave privada RSA codificado em PEM.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

Especifica a chave pública ou o certificado público usado para validar a assinatura num token de acesso formatado em JWT assinado com um algoritmo RSA. Use o atributo ref para transmitir a chave/certificado numa variável de fluxo. Use apenas quando o valor do elemento Algorithm for um dos seguintes: RS256, RS384 ou RS512.

Predefinição	N/A
Presença	Para validar um JWT assinado com um algoritmo RSA, tem de usar os elementos Certificate, JWKS ou Value.
Tipo	String
Valores válidos	Uma variável de fluxo ou uma string.

Elemento <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Especifica onde o Apigee deve procurar o parâmetro redirect_uri no pedido.

Acerca dos URIs de redirecionamento

Os URIs de redirecionamento são usados com os tipos de concessão implícita e de código de autorização. O URI de redirecionamento indica ao servidor de autorização (Apigee) para onde enviar um código de autorização (para o tipo de concessão com código de autorização) ou um token de acesso (para o tipo de concessão implícita). É importante compreender quando este parâmetro é obrigatório, quando é opcional e como é usado:

• (obrigatório) Se um URL de retorno de chamada estiver registado na app do programador associada às chaves de cliente do pedido e se o redirect_uri estiver presente no pedido, os dois têm de corresponder exatamente. Se não corresponderem, é devolvido um erro. Para ver informações sobre o registo de apps de programadores no Apigee e a especificação de um URL de retorno de chamada, consulte o artigo Registe apps e faça a gestão das chaves da API.

  Nota: para garantir que o Apigee verifica uma correspondência exata entre o "URL de retorno de chamada" e o "redirect_uri" (em vez de uma correspondência direta), defina a seguinte propriedade na sua organização: features.isStrictOAuthUriValidation = true. O valor predefinido é false (correspondência direta).

  Contacte o apoio técnico do Google Cloud para ativar a propriedade.

• (Opcional) Se um URL de callback estiver registado e o redirect_uri estiver em falta na solicitação, o Apigee redireciona para o URL de callback registado.
• (obrigatório) Se não estiver registado um URL de retorno de chamada, o elemento redirect_uri é obrigatório. Tenha em atenção que, neste caso, o Apigee aceita QUALQUER URL. Esta situação pode apresentar um problema de segurança e, por isso, só deve ser usada com apps cliente fidedignas. Se as apps cliente não forem fidedignas, a prática recomendada é exigir sempre o registo de um URL de retorno de chamada.

Pode enviar este parâmetro num parâmetro de consulta ou num cabeçalho. A variável request.queryparam.redirect_uri indica que o RedirectUri deve estar presente como um parâmetro de consulta, como, por exemplo, ?redirect_uri=login.myapp.com. Para exigir o RedirectUri num cabeçalho HTTP, por exemplo, defina este valor como request.header.redirect_uri. Consulte também o artigo Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.redirect_uri (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	String
Valores válidos	Qualquer variável de fluxo acessível na política em tempo de execução
Usado com tipos de concessão	authorization_code implícita Também usado com a operação GenerateAuthorizationCode.

Elemento <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Quando solicitar uma chave de acesso através de um símbolo de atualização, tem de fornecer o símbolo de atualização no pedido. Este elemento permite especificar onde o Apigee deve procurar o token de atualização. Por exemplo, pode ser enviado como um parâmetro de consulta, um cabeçalho HTTP ou um parâmetro de formulário (a predefinição).

A variável request.queryparam.refreshtoken indica que o token de atualização deve estar presente como um parâmetro de consulta, como, por exemplo, ?refresh_token=login.myapp.com. Para exigir o RefreshToken num cabeçalho HTTP, por exemplo, defina este valor como request.header.refresh_token. Consulte também o artigo Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.refresh_token (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	String
Valores válidos	Qualquer variável de fluxo acessível na política em tempo de execução
Usado com tipos de concessão	refresh_token

Elemento <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Impõe o tempo de validade dos tokens de atualização em milissegundos. O valor do tempo de expiração é um valor gerado pelo sistema mais o valor de <RefreshTokenExpiresIn>. Se <RefreshTokenExpiresIn> não for especificado, o sistema aplica o valor predefinido.

O tempo de expiração também pode ser definido no tempo de execução através de um valor predefinido codificado ou fazendo referência a uma variável de fluxo. Por exemplo, pode armazenar um valor de expiração do token num mapa de chave-valor, obtê-lo, atribuí-lo a uma variável e fazer referência ao mesmo na política. Por exemplo, kvm.oauth.expires_in.

A stanza seguinte especifica uma variável de fluxo e também um valor predefinido. Tenha em atenção que o valor da variável do fluxo tem precedência sobre o valor predefinido especificado.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

Predefinição	2592000000 ms (30 dias) (em vigor a partir de 31 de maio de 2023)
Presença	Opcional
Tipo	Número inteiro
Valores válidos	Qualquer número inteiro positivo diferente de zero. Especifica o tempo de validade em milissegundos.
Usado com tipos de concessão	authorization_code palavra-passe refresh_token

Elemento <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Este elemento informa o Apigee sobre o tipo de autorização que a app cliente está a pedir. É usado apenas com os fluxos do tipo de concessão implícita e do código de autorização.

Por predefinição, o Apigee procura o valor do tipo de resposta num parâmetro de consulta response_type. Se quiser substituir este comportamento predefinido, use o elemento <ResponseType> para configurar uma variável de fluxo que contenha o valor do tipo de resposta. Por exemplo, se definir este elemento como request.header.response_type, o Apigee procura o tipo de resposta a ser transmitido no cabeçalho do pedido. Consulte também o artigo Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.response_type (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional. Use este elemento se quiser substituir o comportamento predefinido.
Tipo	String
Valores válidos	code (para o tipo de concessão de código de autorização) ou token (para o tipo de concessão implícita)
Usado com tipos de concessão	implícita Também usado com a operação GenerateAuthorizationCode.

Elemento <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Quando definido como true, o token de atualização existente é reutilizado até expirar. Se false, o Apigee emite um novo token de atualização quando é apresentado um token de atualização válido.

Predefinição	false
Presença	opcional
Tipo	booleano
Valores válidos	true ou false
Usado com tipos de concessão	refresh_token

Elemento <RFCCompliantRequestResponse>

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

A política OAuthV2, com a operação GenerateAccessToken, pode devolver uma resposta que não está em conformidade com as especificações relacionadas do IETF OAuth 2.0, incluindo a RFC 6749 e a RFC 6750. Se incluir o elemento RFCCompliantRequestResponse na sua política, com um valor de true, a política OAuthV2 devolve uma resposta em conformidade com a RFC.

A tabela seguinte mostra as diferenças em alguns valores devolvidos pela política OAuthV2, consoante o elemento RFCCompliantRequestResponse seja true ou false.

Elemento	O valor é falso ou está ausente	O valor é verdadeiro
Cache-Control Cabeçalho HTTP	Nenhum fornecido	As respostas de erro e sem erro incluem o campo do cabeçalho de resposta HTTP Cache-Control para agir em conformidade com a RFC2616 (Hypertext Transfer Protocol – HTTP/1.1), com um valor de no-store em qualquer resposta que contenha tokens, credenciais ou outras informações confidenciais, bem como o campo do cabeçalho de resposta Pragma com um valor de no-cache.
"token_type" propriedade na resposta do token válido	Um valor token_type não em conformidade. { ... "token_type": "BearerToken", ... }	Um valor token_type em conformidade. { ... "token_type": "Bearer", ... }
Propriedades "expires_in" e "refresh_token_expires_in" numa resposta de token válida	O valor numérico está entre aspas. Exemplo: { ... "expires_in": "3600", "refresh_token_expires_in": "345600", ... }	O valor é serializado como um número e não como uma string. Exemplo: { ... "expires_in": 3600, "refresh_token_expires_in": 345600, ... }
resposta de erro para um token de atualização expirado quando grant_type = refresh_token	As respostas de erro não estavam em conformidade com a RFC 6749. Exemplo: { "ErrorCode": "InvalidRequest", "Error": "Refresh Token expired" }	As cargas úteis de resposta de erro incluem os elementos "error" e "error_description". Exemplo: { "error": "invalid_grant", "error_description": "refresh token expired" }

Nota: a resposta da Apigee inclui algumas propriedades que não são mencionadas explicitamente na RFC 6749. A especificação permite propriedades adicionais. Para personalizar a resposta de modo a conter apenas as propriedades de que precisa, use o elemento GenerateResponseElement definido como false e, de seguida, use uma política AssignMessage ou JavaScript para gerar o seu próprio payload de resposta.

Predefinição	false: por predefinição, a política apresenta determinados comportamentos não conformes com a RFC, conforme descrito acima.
Presença	Opcional
Tipo	Booleano
Valores válidos	true ou false
Usado com tipos de concessão	Tudo

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

Fornece a chave secreta usada para validar ou assinar tokens de acesso formatados em JWT com um algoritmo HMAC. Use apenas quando o algoritmo for um de HS256, HS384 ou HS512. Use o atributo ref para transmitir a chave numa variável de fluxo. Para mais informações, consulte o artigo Usar operações de tokens OAuth JWT.

O Apigee aplica uma intensidade mínima da chave para os algoritmos HS256/HS384/HS512. O comprimento mínimo da chave para HS256 é de 32 bytes, para HS384 é de 48 bytes e para HS512 é de 64 bytes. A utilização de uma chave de menor intensidade provoca um erro de tempo de execução.

Nota: para proteger segredos, é uma prática recomendada armazenar a chave num conjunto de propriedades com âmbito do ambiente ou num mapa de valores-chave (KVM) com âmbito do ambiente. Consulte também Aceda aos valores definidos da propriedade e Use mapas de valores-chave.

Predefinição	N/A
Presença	Obrigatório para algoritmos HMAC.
Tipo	String
Valores válidos	Uma variável de fluxo

Elemento <Scope>

<Scope>request.queryparam.scope</Scope>

Se este elemento estiver presente numa das políticas GenerateAccessToken ou GenerateAuthorizationCode, é usado para especificar os âmbitos a conceder ao token ou ao código. Normalmente, estes valores são transmitidos para a política no pedido de uma app cliente. Pode configurar o elemento para receber uma variável de fluxo, o que lhe dá a opção de escolher como os âmbitos são transmitidos num pedido. No exemplo seguinte, request.queryparam.scope indica que o âmbito deve estar presente como um parâmetro de consulta, como, por exemplo, ?scope=READ. Para exigir o âmbito num cabeçalho HTTP, por exemplo, defina este valor como request.header.scope.

Se este elemento aparecer numa política "VerifyAccessToken", é usado para especificar os âmbitos que a política deve aplicar. Neste tipo de política, o valor tem de ser um nome de âmbito "codificado". Não pode usar variáveis. Por exemplo:

<Scope>A B</Scope>

Consulte também os artigos Trabalhar com âmbitos do OAuth2 e Obter tokens do OAuth 2.0.

Predefinição	Sem âmbito
Presença	Opcional
Tipo	String
Valores válidos	Se for usado com políticas Generate*, uma variável de fluxo. Se for usado com VerifyAccessToken, uma lista de nomes de âmbitos (strings) separados por espaços.
Usado com tipos de concessão	authorization_code implícita palavra-passe client_credentials Também pode ser usado com as operações GenerateAuthorizationCode e VerifyAccessToken.

Elemento <State>

<State>request.queryparam.state</State>

Nos casos em que a app cliente tem de enviar as informações de estado para o servidor de autorização, este elemento permite-lhe especificar onde o Apigee deve procurar os valores de estado. Por exemplo, pode ser enviado como um parâmetro de consulta ou num cabeçalho HTTP. Normalmente, o valor do estado é usado como uma medida de segurança para evitar ataques CSRF.

Por exemplo, request.queryparam.state indica que o estado deve estar presente como um parâmetro de consulta, como, por exemplo, ?state=HjoiuKJH32. Para exigir o estado num cabeçalho HTTP, por exemplo, defina este valor como request.header.state. Consulte também Obtenha tokens OAuth 2.0.

Predefinição	Nenhum estado
Presença	Opcional
Tipo	String
Valores válidos	Qualquer variável de fluxo acessível à política no tempo de execução
Usado com tipos de concessão	Tudo Também pode ser usado com a operação GenerateAuthorizationCode

Elemento <StoreToken>

 <StoreToken>true</StoreToken>

Defina este elemento como true quando o elemento <ExternalAuthorization> for true. O elemento <StoreToken> indica ao Apigee que deve armazenar o token de acesso externo. Caso contrário, não é mantido.

Predefinição	falso
Presença	Opcional
Tipo	Booleano
Valores válidos	verdadeiro ou falso
Usado com tipos de concessão	authorization_code palavra-passe client_credentials

<SupportedGrantTypes>/<GrantType> element

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Especifica os tipos de concessão suportados por um ponto final de token OAuth no Apigee. Um ponto final pode suportar vários tipos de concessão (ou seja, um único ponto final pode ser configurado para distribuir tokens de acesso para vários tipos de concessão). Para mais informações sobre os pontos finais, consulte o artigo Compreender os pontos finais de OAuth. O tipo de autorização é transmitido em pedidos de tokens num parâmetro grant_type

Se não forem especificados tipos de concessão suportados, os únicos tipos de concessão permitidos são authorization_code e implicit. Consulte também o elemento <GrantType> (que é um elemento de nível superior usado para especificar onde o Apigee deve procurar o parâmetro grant_type transmitido num pedido do cliente. O Apigee garante que o valor do parâmetro grant_type corresponde a um dos tipos de autorização suportados.

Predefinição	authorization_code e implícito
Presença	Obrigatória
Tipo	String
Valores válidos	client_credentials authorization_code palavra-passe implícita

Elemento <Tokens>/<Token>

Usado com as operações ValidateToken e InvalidateToken. Consulte também o artigo Aprovar e revogar tokens de acesso. O elemento <Token> identifica a variável de fluxo que define a origem do token a ser revogado. Se os programadores tiverem de enviar tokens de acesso como parâmetros de consulta denominados access_token, por exemplo, use request.queryparam.access_token.

Elemento <UserName>

<UserName>request.queryparam.user_name</UserName>

Este elemento é usado apenas com o tipo de concessão de palavra-passe. Com o tipo de autorização de palavra-passe, as credenciais do utilizador (palavra-passe e nome de utilizador) têm de ser disponibilizadas à política OAuthV2. Os elementos <PassWord> e <UserName> são usados para especificar variáveis onde o Apigee pode encontrar estes valores. Se estes elementos não forem especificados, a política espera encontrar os valores (por predefinição) nos parâmetros do formulário denominados username e password. Se os valores não forem encontrados, a política gera um erro. Pode usar os elementos <PassWord> e <UserName> para fazer referência a qualquer variável de fluxo que contenha as credenciais.

Por exemplo, pode transmitir o nome de utilizador num parâmetro de consulta e definir o elemento <UserName> da seguinte forma: <UserName>request.queryparam.username</UserName>.para exigir o nome de utilizador num cabeçalho HTTP, defina este valor como request.header.username.

A política OAuthV2 não faz mais nada com estes valores de credenciais. O Apigee está simplesmente a verificar se estão presentes. É da responsabilidade do programador da API obter os valores pedidos e enviá-los a um fornecedor de identidade antes de a política de geração de tokens ser executada.

Consulte também o artigo Obtenha tokens OAuth 2.0.

Predefinição	request.formparam.username (um x-www-form-urlencoded e especificado no corpo do pedido)
Presença	Opcional
Tipo	String
Valores válidos	Qualquer definição de variável.
Usado com tipos de concessão	palavra-passe

Validar tokens de acesso

Assim que um ponto final de token é configurado para um proxy de API, é anexada uma política OAuthV2 correspondente que especifica a operação VerifyAccessToken ao fluxo que expõe o recurso protegido.

Por exemplo, para garantir que todos os pedidos a uma API estão autorizados, a seguinte política impõe a validação do token de acesso:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

A política está anexada ao recurso da API a proteger. Para garantir que todos os pedidos a uma API são validados, anexe a política ao PreFlow do pedido ProxyEndpoint, da seguinte forma:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Os seguintes elementos opcionais podem ser usados para substituir as definições predefinidas da operação VerifyAccessToken.

Nome	Descrição
Âmbito	Uma lista de âmbitos delimitada por espaços. A validação é bem-sucedida se, pelo menos, um dos âmbitos indicados estiver presente na chave de acesso. Por exemplo, a seguinte política vai verificar o token de acesso para garantir que contém, pelo menos, um dos âmbitos indicados. Se READ ou WRITE estiver presente, a validação é bem-sucedida. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2>
AccessToken	A variável onde se espera que o token de acesso esteja localizado. Por exemplo request.queryparam.accesstoken. Por predefinição, espera-se que a app apresente o token de acesso no cabeçalho HTTP de autorização, de acordo com a especificação OAuth 2.0. Use esta definição se o token de acesso for apresentado numa localização não padrão, como um parâmetro de consulta ou um cabeçalho HTTP com um nome diferente de Autorização.

Consulte também Validar tokens de acesso e Obter tokens OAuth 2.0.

Especificar localizações de variáveis de pedidos

Para cada tipo de concessão, a política faz suposições sobre a localização ou as informações necessárias nas mensagens de solicitação. Estas suposições baseiam-se na especificação OAuth 2.0. Se as suas apps precisarem de se desviar da especificação OAuth 2.0, pode especificar as localizações esperadas para cada parâmetro. Por exemplo, ao processar um código de autorização, pode especificar a localização do código de autorização, o ID de cliente, o URI de redirecionamento e o âmbito. Estes podem ser especificados como cabeçalhos HTTP, parâmetros de consulta ou parâmetros de formulário.

O exemplo abaixo demonstra como pode especificar a localização dos parâmetros do código de autorização obrigatórios como cabeçalhos HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Em alternativa, se for necessário para suportar a base de apps de cliente, pode combinar cabeçalhos e parâmetros de consulta:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Só é possível configurar uma localização por parâmetro.

Variáveis de fluxo

As variáveis de fluxo definidas nesta tabela são preenchidas quando as respetivas políticas OAuth são executadas e, por isso, estão disponíveis para outras políticas ou aplicações que são executadas no fluxo do proxy de API.

Operação VerifyAccessToken

Quando a operação VerifyAccessToken é executada, um grande número de variáveis de fluxo é preenchido no contexto de execução do proxy. Estas variáveis dão-lhe propriedades relacionadas com o token de acesso, a app do programador e o programador. Pode usar uma política AssignMessage ou JavaScript, por exemplo, para ler qualquer uma destas variáveis e usá-las conforme necessário mais tarde no fluxo. Estas variáveis também podem ser úteis para fins de depuração.

Nota: as variáveis do produto API são preenchidas automaticamente se os produtos API estiverem configurados com um ambiente, proxies e recursos API válidos (derivados do proxy.pathsuffix). Não é necessário definir explicitamente a variável flow.resource.name.

Quando os produtos de API não estão configurados com ambientes e proxies de API válidos, o elemento flow.resource.name tem de ser definido explicitamente para preencher as variáveis do produto de API no fluxo. Para ver detalhes sobre a configuração de produtos, consulte o artigo Gerir produtos de API.

Variáveis específicas do token

Variáveis	Descrição
organization_name	O nome da organização onde o proxy está a ser executado.
developer.id	O ID do programador ou do AppGroup associado à app cliente registada.
developer.app.name	O nome do programador ou da app do AppGroup associada à app cliente registada.
client_id	O ID de cliente da app cliente registada.
grant_type	O tipo de autorização associado ao pedido. Não suportado para a operação VerifyJWTAccessToken.
token_type	O tipo de token associado ao pedido.
access_token	O token de acesso que está a ser validado.
accesstoken.{custom_attribute}	Um atributo personalizado com nome no token de acesso.
issued_at	A data em que o token de acesso foi emitido, expressa em tempo de época Unix em milissegundos.
expires_in	A hora de validade do token de acesso. Expresso em segundos. Embora o elemento ExpiresIn defina o prazo de validade em milissegundos, na resposta do token e nas variáveis do fluxo, o valor é expresso em segundos.
status	O estado do token de acesso (por exemplo, aprovado ou revogado).
scope	O âmbito (se existir) associado ao token de acesso.
apiproduct.<custom_attribute_name>	Um atributo personalizado com nome do produto da API associado à app cliente registada.
apiproduct.name	O nome do produto API associado à app cliente registada.
revoke_reason	(Apenas para o Apigee hybrid) Indica o motivo pelo qual a chave de acesso é revogada. Não suportado para a operação VerifyJWTAccessToken. O valor pode ser REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER ou TOKEN_REVOKED.

Variáveis específicas da app

Estas variáveis estão relacionadas com a app de programador associada ao token.

Variáveis	Descrição
app.name
app.id
app.accessType
app.callbackUrl
app.status	aprovado ou revogado
app.scopes
app.appFamily
app.apiproducts
app.appParentStatus
app.appType	Por exemplo: Developer
app.appParentId
app.created_by
app.created_at
app.last_modified_at
app.last_modified_by
app.{custom_attributes}	Um atributo personalizado com nome da app cliente registada.

Variáveis específicas do grupo de apps

As seguintes variáveis de fluxo contêm informações sobre o AppGroup para o token e são preenchidas pela política. Estes atributos AppGroup são preenchidos apenas se verifyapikey.{policy_name}.app.appType for "AppGroup".

Nota: se migrar do Apigee Edge, as variáveis de fluxo da empresa ficam automaticamente disponíveis no atributo AppGroup correspondente após a migração. Não são necessárias alterações aos pacotes durante a migração.

Variáveis	Descrição
appgroup.displayName	O nome a apresentar do grupo de apps.
appgroup.name	Nome do AppGroup.
appgroup.id	O ID do grupo de apps. Nota: este ID é gerado internamente pelo Apigee e não é garantido que permaneça o mesmo ao longo do tempo. Não use a variável appgroup.id para nenhum dos seguintes fins: Identificador de quota Teclas KVM Identificadores enviados para alvos a serem usados na lógica empresarial de back-end
appOwnerStatus	O estado do proprietário da app: "active", "inactive" ou "login_lock".
created_at	A data/hora em que o AppGroup foi criado.
created_by	O endereço de email do programador que criou o AppGroup.
last_modified_at	A data/hora em que o AppGroup foi modificado pela última vez.
last_modified_by	O endereço de email do programador que modificou o AppGroup pela última vez.
{appgroup_custom_attributes}	Qualquer atributo personalizado do grupo de apps. Especifique o nome do atributo personalizado.

Variáveis específicas do programador

Se o app.appType for "Programador", os atributos do programador são preenchidos.

Variáveis	Descrição
Variáveis específicas do programador
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status	ativas ou inativas
developer.apps	Nota: o acesso a esta variável resulta numa latência elevada quando o número de apps é superior a 10.
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes}	Um atributo personalizado com nome do programador.

Operação GenerateAuthorizationCode

Estas variáveis são definidas quando a operação GenerateAuthorizationCode é executada com êxito:

Prefixo: oauthv2authcode.{policy_name}.{variable_name}

Exemplo: oauthv2authcode.GenerateCodePolicy.code

Variável	Descrição
code	O código de autorização gerado quando a política é executada.
redirect_uri	O URI de redirecionamento associado à app cliente registada.
scope	O âmbito OAuth opcional transmitido no pedido do cliente.
client_id	O ID de cliente transmitido no pedido do cliente.

Operações GenerateAccessToken e RefreshAccessToken

Estas variáveis são definidas quando as operações GenerateAccessToken e RefreshAccessToken são executadas com êxito. Tenha em atenção que as variáveis do token de atualização não se aplicam ao fluxo do tipo de concessão de credenciais de cliente.

Prefixo: oauthv2accesstoken.{policy_name}.{variable_name}

Exemplo: oauthv2accesstoken.GenerateTokenPolicy.access_token

Nome da variável	Descrição
access_token	O token de acesso que foi gerado.
client_id	O ID de cliente da app de programador associada a este token.
expires_in	O valor de validade do token. Consulte o elemento <ExpiresIn> para ver detalhes. Tenha em atenção que, na resposta, expires_in é expresso em segundos.
scope	Lista de âmbitos disponíveis configurados para o token. Consulte o artigo Trabalhar com âmbitos de OAuth2.
status	approved ou revoked.
token_type	Está definido como BearerToken.
developer.email	O endereço de email do programador registado proprietário da app de programador associada ao token.
organization_name	A organização onde o proxy é executado.
api_product_list	Uma lista dos produtos associados à app de programador correspondente do token.
refresh_count
refresh_token	O token de atualização que foi gerado. Tenha em atenção que os tokens de atualização não são gerados para o tipo de autorização de credenciais de cliente.
refresh_token_expires_in	A duração do token de atualização, em segundos.
refresh_token_issued_at	Este valor temporal é a representação de string da quantidade de data/hora de 32 bits correspondente. Por exemplo, "Wed, 21 Aug 2013 19:16:47 UTC" corresponde ao valor de data/hora de 1377112607413.
refresh_token_status	approved ou revoked.

GenerateAccessTokenImplicitGrant

Estas variáveis são definidas quando a operação GenerateAccessTokenImplicit é executada com êxito para o fluxo do tipo de autorização implícito.

Prefixo: oauthv2accesstoken.{policy_name}.{variable_name}

Exemplo: oauthv2accesstoken.RefreshTokenPolicy.access_token

Variável	Descrição
oauthv2accesstoken.access_token	O token de acesso gerado quando a política é executada.
oauthv2accesstoken.{policy_name}.expires_in	O valor de validade do token, em segundos. Consulte o elemento <ExpiresIn> para ver detalhes.

Referência de erros

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 Como processar falhas.

Erros de tempo de execução

Estes erros podem ocorrer quando a política é executada.

Código de falha	Estado de HTTP	Causa	Gerado por operações
steps.oauth.v2.access_token_expired	401	O token de acesso expirou.	VerifyAccessToken InvalidateToken
steps.oauth.v2.access_token_not_approved	401	A chave de acesso foi revogada.	VerifyAccessToken
steps.oauth.v2.apiproduct_doesnot_exist	401	O produto API pedido não existe em nenhum dos produtos API associados ao token de acesso.	VerifyAccessToken
steps.oauth.v2.FailedToResolveAccessToken	500	A política esperava encontrar um token de acesso numa variável especificada no elemento <AccessToken>, mas não foi possível resolver a variável.	GenerateAccessToken
steps.oauth.v2.FailedToResolveAuthorizationCode	500	A política esperava encontrar um código de autorização numa variável especificada no elemento <Code>, mas não foi possível resolver a variável.	GenerateAuthorizationCode
steps.oauth.v2.FailedToResolveClientId	500	A política esperava encontrar o ID do cliente numa variável especificada no elemento <ClientId>, mas não foi possível resolver a variável.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
steps.oauth.v2.FailedToResolveRefreshToken	500	A política esperava encontrar um token de atualização numa variável especificada no elemento <RefreshToken>, mas não foi possível resolver a variável.	RefreshAccessToken
steps.oauth.v2.FailedToResolveToken	500	A política esperava encontrar um token numa variável especificada no elemento <Tokens>, mas não foi possível resolver a variável.	ValidateToken InvalidateToken
steps.oauth.v2.InsufficientScope	403	O token de acesso apresentado no pedido tem um âmbito que não corresponde ao âmbito especificado na política de verificação do token de acesso. Para saber mais sobre o âmbito, consulte o artigo Trabalhar com âmbitos do OAuth2.	VerifyAccessToken
steps.oauth.v2.invalid_client	401	Este nome de erro é devolvido quando a propriedade <GenerateResponse> da política está definida como true e o ID do cliente enviado no pedido é inválido. Verifique se está a usar os valores da chave e do segredo do cliente corretos para a app de programador associada ao seu proxy. Normalmente, estes valores são enviados como um cabeçalho de autorização básica codificado em Base64. Nota: recomendamos que altere as condições das regras de falhas existentes para captar os nomes invalid_client e InvalidClientIdentifier.	GenerateAccessToken RefreshAccessToken
steps.oauth.v2.InvalidRequest	400	Este nome de erro é usado para vários tipos diferentes de erros, normalmente para parâmetros em falta ou incorretos enviados no pedido. Se <GenerateResponse> estiver definido como false, use variáveis de falha (descritas abaixo) para obter detalhes sobre o erro, como o nome e a causa da falha.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken
steps.oauth.v2.InvalidAccessToken	401	O cabeçalho de autorização não tem a palavra Bearer, que é obrigatória. Por exemplo: Authorization: Bearer your_access_token	VerifyAccessToken
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound	401	O proxy ou a operação da API em execução atualmente não está no produto associado ao token de acesso. Sugestões: certifique-se de que o produto associado ao token de acesso está configurado corretamente. Por exemplo, se usar carateres universais em caminhos de recursos, certifique-se de que os carateres universais estão a ser usados corretamente. Consulte o artigo Gerir produtos da API para ver detalhes. Veja também A validação do token de acesso Oauth2.0 gera o erro "Invalid API call as no apiproduct match found" para obter mais orientações sobre as causas deste erro.	VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier	500	Este nome de erro é devolvido quando a propriedade <GenerateResponse> da política está definida como false e o ID do cliente enviado no pedido é inválido. Verifique se está a usar os valores da chave secreta e da chave do cliente corretos para a app de programador associada ao seu proxy. Normalmente, estes valores são enviados como um cabeçalho de autorização básica codificado em Base64. Nota: recomendamos que altere as condições das regras de falhas existentes para captar os nomes invalid_client e InvalidClientIdentifier.	GenerateAccessToken RefreshAccessToken
steps.oauth.v2.InvalidParameter	500	A política tem de especificar um token de acesso ou um código de autorização, mas não ambos.	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
steps.oauth.v2.InvalidTokenType	500	O elemento <Tokens>/<Token> requer que especifique o tipo de token (por exemplo, refreshtoken). Se o cliente transmitir o tipo errado, este erro é gerado.	ValidateToken InvalidateToken
steps.oauth.v2.MissingParameter	500	O tipo de resposta é token, mas não foram especificados tipos de autorização.	GenerateAuthorizationCode GenerateAccessTokenImplicitGrant
steps.oauth.v2.UnSupportedGrantType	500	O cliente especificou um tipo de concessão não suportado pela política (não listado no elemento <SupportedGrantTypes>). Nota: atualmente, existe um erro em que os erros de tipo de autorização não suportados não são apresentados corretamente. Se ocorrer um erro de tipo de concessão não suportado, o proxy não entra no fluxo de erros, como esperado.	GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken

Erros de tempo de execução específicos do token JWT

Os códigos e as descrições de erros de tempo de execução para fluxos de tokens de autorização JWT dependem do contexto do fluxo OAuth2:

• Se o contexto do fluxo for a geração ou a atualização de tokens, consulte os códigos de erro para a geração e a atualização de tokens JWT abaixo.
• Para o fluxo de validação de tokens, consulte os códigos de erro para fluxos de validação de tokens abaixo.

Códigos de erro para a geração de tokens JWT e fluxos de atualização

Para fluxos OAuth2 que geram ou atualizam tokens JWT, as respostas de erro cumprem as respostas de erro especificadas na RFC6749. Para ver detalhes, consulte a secção 5.2 Resposta de erro.

Códigos de erro para o fluxo de validação de tokens

Os códigos de erro indicados na tabela seguinte aplicam-se apenas à operação VerifyAccessToken.

Código de falha	Estado de HTTP	Causa	Gerado por operações
oauth.v2.JWTSigningFailed	401	A política não conseguiu assinar o JWT.	GenerateJWTAccessToken
oauth.v2.InvalidValueForJWTAlgorithm	401	Isto ocorre quando o algoritmo não está presente no token de acesso JWT ou quando o valor não é suportado.	GenerateJWTAccessToken VerifyJWTAccessToken
oauth.v2.InsufficientKeyLength	401	Na geração de JWT, para uma chave inferior ao tamanho mínimo para os algoritmos HS384 ou HS512	GenerateJWTAccessToken VerifyJWTAccessToken
oauth.v2.JWTAlgorithmMismatch	401	O algoritmo especificado na política Generate não correspondeu ao esperado na política Verify. Os algoritmos especificados têm de corresponder.	VerifyJWTAccessToken
oauth.v2.JWTDecodingFailed	401	A política não conseguiu descodificar o JWT. O JWT está possivelmente danificado.	VerifyJWTAccessToken
oauth.v2.MissingMandatoryClaimsInJWT	401	Ocorre quando as reivindicações necessárias não estão presentes na chave de acesso JWT	VerifyJWTAccessToken
oauth.v2.InvalidJWTSignature	401	Isto ocorre quando não foi possível validar a assinatura do token de acesso JWT ou quando a assinatura é inválida.	VerifyJWTAccessToken
oauth.v2.InvalidTypeInJWTHeader	401	Ocorre quando o tipo do JWT não é at+Jwt	VerifyJWTAccessToken

Erros de implementação

Estes erros podem ocorrer quando implementa um proxy que contém esta política.

Nome do erro	Causa
InvalidValueForExpiresIn	Para o elemento <ExpiresIn>, os valores válidos são números inteiros positivos.
InvalidValueForRefreshTokenExpiresIn	Para o elemento <RefreshTokenExpiresIn>, os valores válidos são números inteiros positivos.
InvalidGrantType	É especificado um tipo de autorização inválido no elemento <SupportedGrantTypes>. Consulte a referência da política para ver uma lista de tipos válidos.
ExpiresInNotApplicableForOperation	Certifique-se de que as operações especificadas no elemento <Operations> suportam a expiração. Por exemplo, a operação VerifyToken não o faz.
RefreshTokenExpiresInNotApplicableForOperation	Certifique-se de que as operações especificadas no elemento <Operations> suportam a validade do token de atualização. Por exemplo, a operação VerifyToken não o faz.
GrantTypesNotApplicableForOperation	Certifique-se de que os tipos de autorização especificados em <SupportedGrantTypes> são suportados para a operação especificada.
OperationRequired	Tem de especificar uma operação nesta política através do elemento <Operation>. Nota: se o elemento <Operation> estiver em falta, a interface do utilizador gera um erro de validação do esquema.
InvalidOperation	Tem de especificar uma operação válida nesta política através do elemento <Operation>. Nota: se o elemento <Operation> for inválido, a IU gera um erro de validação do esquema.
TokenValueRequired	Tem de especificar um valor de token <Token> no elemento <Tokens>.

Erros de implementação específicos do token JWT

Estes erros de implementação são específicos das políticas que usam operações de tokens JWT.

Nome do erro	Causa
InvalidValueForAlgorithm	O algoritmo especificado no elemento <Algorithm> não está na lista de algoritmos disponíveis ou não está presente.
MissingKeyConfiguration	Os elementos obrigatórios <SecretKey>, <PrivateKey> ou <PublicKey> estão em falta, consoante o algoritmo usado.
EmptyValueElementForKeyConfiguration	O elemento secundário obrigatório <Value> não está definido nos elementos <PrivateKey>, <PublicKey> ou <SecretKey>
InvalidKeyConfiguration	O elemento <PrivateKey> não é usado com algoritmos da família RSA ou o elemento <SecretKey> não é usado com algoritmos da família HS.
EmptyRefAttributeForKeyconfiguration	O atributo ref do elemento secundário <Value> dos elementos <PrivateKey>, <PublicKey> ou <SecretKey> está vazio.
InvalidVariableNameForKey	O nome da variável de fluxo especificado no atributo ref do elemento secundário <Value> dos elementos <PrivateKey>, <PublicKey> ou <SecretKey> não contém o prefixo private.

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. Estas variáveis são preenchidas quando ocorre um erro se <GenerateResponse> estiver definido como false. Se <GenerateResponse> for true, a política devolve uma resposta ao cliente imediatamente se ocorrer um erro. O fluxo de erros é ignorado e estas variáveis não são preenchidas. Para mais informações, consulte o artigo O que precisa de saber sobre os 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 = "InvalidRequest"
oauthV2.policy_name.failed	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	oauthV2.GenerateAccesstoken.failed = true
oauthV2.policy_name.fault.name	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	oauthV2.GenerateAccesstoken.fault.name = InvalidRequest Nota: para a operação VerifyAccessToken, o nome da falha inclui este sufixo: keymanagement.service Por exemplo: keymanagement.service.invalid_access_token
oauthV2.policy_name.fault.cause	policy_name é o nome especificado pelo utilizador da política que gerou a falha.	oauthV2.GenerateAccesstoken.cause = Required param : grant_type

Exemplo de resposta de erro

Estas respostas são enviadas de volta para o cliente se o elemento <GenerateResponse> for true.

Nota: para o processamento de erros, a prática recomendada é capturar a parte errorcode da resposta de erro. Não confie no texto no elemento faultstring, porque pode mudar.

Se <GenerateResponse> for verdadeiro, a política devolve erros neste formato para operações que geram tokens e códigos. Para ver uma lista completa, consulte a referência da resposta de erro HTTP do OAuth.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Se <GenerateResponse> for verdadeiro, a política devolve erros neste formato para operações de verificação e validação. Para ver uma lista completa, consulte a referência da resposta de erro HTTP do OAuth.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Exemplo de regra de falha

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Os tokens no armazenamento são hash

Se estiver a usar o Apigee hybrid ou o Apigee, os tokens de acesso OAuthV2 e os tokens de atualização são aplicados por predefinição quando armazenados na base de dados Cassandra de tempo de execução. A aplicação de hash impede a utilização dos tokens se a base de dados for comprometida.

Trabalhar com a configuração OAuth predefinida

Cada organização (mesmo uma organização de avaliação gratuita) no Apigee é aprovisionada com um ponto final do token OAuth. O ponto final está pré-configurado com políticas no proxy de API denominado oauth. Pode começar a usar o ponto final do token assim que criar uma conta no Apigee. Para mais detalhes, consulte o artigo Compreender os pontos finais do OAuth.

Limpar chaves de acesso

Por predefinição, as chaves OAuth2 são eliminadas do sistema Apigee 3 dias (259 200 segundos) após a expiração da chave de acesso e da chave de atualização (se existir).

Tópicos relacionados

• Introdução ao OAuth 2.0