Você está visualizando a documentação do Apigee Edge.
Acesse a documentação da
Apigee X. informações
O que
OAuthV2 é uma política multifacetada para executar operações do tipo de concessão OAuth 2.0. Essa é a política principal usada para configurar os endpoints do OAuth 2.0 na Apigee Edge.
Dica:se você quer saber mais sobre o OAuth no Apigee Edge, consulte a página inicial do OAuth. Ela fornece links para recursos, amostras, vídeos e muito mais. Consulte o exemplo avançado de OAuth no GitHub para ver uma boa demonstração de como essa política é usada em um aplicativo funcional.
Amostras
VerifyAccessToken
VerifyAccessToken
Essa configuração de política OAuthV2 (com a operação VerifyAccessToken) verifica se um token de acesso enviado ao Apigee Edge é válido. Quando essa operação de política é acionada, o Edge procura um token de acesso válido na solicitação. Se o token de acesso for válido, a solicitação poderá continuar. Se inválido, todos os processamentos serão interrompidos e um erro será retornado na resposta.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2"> <DisplayName>OAuth v2.0 2</DisplayName> <Operation>VerifyAccessToken</Operation> <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer --> </OAuthV2>
Observação: só os tokens do portador do OAuth 2.0 são compatíveis. Tokens de código de autenticação de mensagens (MAC, na sigla em inglês) não são compatíveis.
Exemplo:
$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
Por padrão, o Edge aceita tokens de acesso no cabeçalho Authorization
com
o prefixo Bearer
. É possível alterar esse padrão com o elemento <AccessToken>
.
GenerateAccessToken
Como gerar tokens de acesso
Para ver exemplos de como solicitar tokens de acesso para cada um dos tipos de concessão compatíveis, consulte Como solicitar tokens de acesso e códigos de autorização. O tópico inclui exemplos dessas operações:
GenerateAuthorizationCode
Gerar código de autorização
Para ver exemplos de como solicitar códigos de autorização, consulte Como solicitar um código de autorização.
RefreshAccessToken
Atualizar um token de acesso
Para exemplos de como solicitar tokens de acesso usando um token de atualização, consulte Como atualizar um token de acesso.
Token de fluxo de resposta
Gerar um token de acesso no fluxo de resposta
Às vezes, pode ser necessário gerar um token de acesso no fluxo de resposta. Por exemplo, é possível fazer isso em resposta a uma validação personalizada feita em um serviço de back-end. Neste exemplo, o caso de uso requer um token de acesso e um token de atualização, considerando o tipo de concessão implícito. Nesse caso, usaremos o tipo de concessão de senha para gerar o token. Como você verá, o truque para fazer isso funcionar é passar um cabeçalho de solicitação de autorização com uma política 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 você colocar essa política no fluxo de resposta, ela falhará com um erro 401 UnAuthorized, mesmo que os parâmetros de login corretos sejam especificados na política. Para resolver esse problema, é preciso definir um cabeçalho de solicitação de autorização.
O cabeçalho de autorização precisa conter um esquema de acesso básico com o client_id codificado em Base64:client_secret.
É possível adicionar esse cabeçalho com uma política JavaScript colocada antes da política OAuthV2, como esta. As variáveis "local_clientid" e "local_secret" precisam ser definidas e disponíveis anteriormente no fluxo:
var client_id = context.getVariable("local_clientid"); var client_secret = context.getVariable("local_secret"); context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1 .parse(client_id + ':' + client_secret)));
Consulte também Como codificar credenciais básicas de autenticação.
Referência de elemento
A referência de política descreve os elementos e atributos da política OAuthV2.
A política de amostra mostrada abaixo é uma das configurações possíveis. Este exemplo mostra uma política do OAuthV2 configurada para a operação GenerateAccessToken. Ele inclui elementos obrigatórios e opcionais. Consulte as descrições dos elementos nesta seção para mais 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 de <OAuthV2>
<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">
A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:
Atributo | Descrição | Padrão | Presença |
---|---|---|---|
name |
O nome interno da política. O valor do atributo Opcionalmente, use o elemento |
N/A | Obrigatório |
continueOnError |
Defina como Defina como |
falso | Opcional |
enabled |
Defina como Defina como |
true | Opcional |
async |
Esse atributo está obsoleto. |
falso | Obsoleto |
Elemento <DisplayName>
Use em conjunto com o atributo name
para rotular a política no
editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
<DisplayName>Policy Display Name</DisplayName>
Padrão |
N/A Se você omitir esse elemento, será usado o valor do atributo |
---|---|
Presença | Opcional |
Tipo | String |
Elemento <AccessToken>
<AccessToken>request.header.access_token</AccessToken>
Por padrão, o VerifyAccessToken espera que o token de acesso seja enviado no cabeçalho Authorization
.
Você pode alterar esse padrão usando esse elemento. Por exemplo, request.queryparam.access_token
indica que o token de acesso precisa estar presente como um parâmetro de consulta chamado access_token
.
<AccessToken>request.header.access_token</AccessToken>
é especificado:
curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
<AccessToken>request.queryparam.access_token</AccessToken>
é
especificado:
curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: | String |
Usado com operações: |
|
Elemento <AccessTokenPrefix>
<AccessTokenPrefix>Bearer</AccessTokenPrefix>
Por padrão, o VerifyAccessToken espera que o token de acesso seja enviado no cabeçalho de autorização como um token do portador. Exemplo:
-H "Authorization: Bearer Rft3dqrs56Blirls56a"
Atualmente, o portador é o único prefixo compatível.
Padrão: |
Portador |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: |
Portador |
Usado com operações: |
|
Elemento <AppEndUser>
<AppEndUser>request.queryparam.app_enduser</AppEndUser>
Nos casos em que o ID do usuário final do app precisa ser enviado ao servidor de autorização, esse elemento permite especificar onde o Edge precisa procurar o ID do usuário final. Por exemplo, ele pode ser enviado como um parâmetro de consulta ou em um cabeçalho HTTP.
Por exemplo, request.queryparam.app_enduser
indica que o AppEndUser precisa estar presente como um parâmetro de consulta, como, por exemplo, ?app_enduser=ntesla@theramin.com
. Por exemplo, para exigir o AppEndUser em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.app_enduser
.
Fornecer essa configuração permite que você inclua um ID de usuário final do aplicativo no token de acesso. Esse recurso é útil se você quiser recuperar ou revogar tokens de acesso do OAuth 2.0 por ID do usuário final. Para mais informações, consulte Ativar a recuperação e a revogação de tokens de acesso do OAuth 2.0 por ID de usuário final, ID do aplicativo ou ambos.
Padrão: |
N/A |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: |
Qualquer variável de fluxo acessível para a política no tempo de execução. |
Usado com tipos de concessão: |
|
<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 esse elemento para adicionar atributos personalizados a um token de acesso ou a códigos de autorização. Por exemplo, talvez você queira incorporar um ID de usuário ou identificador de sessão em um token de acesso que possa ser extraído e verificado no ambiente de execução.
Esse elemento permite especificar um valor em uma variável de fluxo ou de uma string literal. Se você especificar uma variável e uma string, o valor especificado na variável de fluxo será usado. Se a variável não puder ser resolvida, a string será o padrão.
Para mais informações sobre como usar esse elemento, consulte Como personalizar tokens e códigos de autorização.
Como exibir ou ocultar atributos personalizados na resposta
Lembre-se de que se você definir o elemento GenerateResponse dessa política como true, a representação JSON completa do token será retornada na resposta, incluindo todos os atributos personalizados que você definir. Em alguns casos, você pode ocultar alguns ou todos os atributos personalizados na resposta para que eles não fiquem visíveis para os apps clientes.
Por padrão, os atributos personalizados aparecem na resposta. Se quiser ocultá-los, defina o parâmetro display como false. 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. Digamos que você gere um token de acesso com atributos personalizados que quer ocultar na resposta gerada. A definição de display=false
atinge essa meta. No entanto, se um novo token de acesso for gerado posteriormente usando um token de atualização, os atributos personalizados originais do token de acesso serão exibidos na resposta do token de atualização. Isso ocorre porque o Edge não se lembra de que
o atributo display
foi definido originalmente como false
na política de geração de tokens de acesso. O atributo personalizado
é simplesmente parte dos metadados do token de acesso.
Você verá o mesmo comportamento se adicionar atributos personalizados a um código de autorização. Quando um token de acesso for gerado usando esse código, esses atributos personalizados serão exibidos na resposta do token de acesso. Novamente, esse pode não ser o comportamento esperado.
Para ocultar atributos personalizados nesses casos, você tem as seguintes opções:
- Redefina explicitamente os atributos personalizados na política de tokens de atualização e defina a exibição deles como "false". Nesse caso, talvez seja necessário recuperar os valores personalizados originais do token de acesso original usando a política GetOAuthV2Info.
- Use uma política JavaScript de pós-processamento para extrair manualmente quaisquer atributos personalizados que você não quer ver na resposta.
Consulte também Como personalizar tokens e códigos de autorização.
Padrão: |
|
Presença: |
Opcional |
Valores válidos: |
|
Usado com tipos de concessão: |
|
Elemento <ClientId>
<ClientId>request.formparam.client_id</ClientId>
Em vários casos, o app cliente precisa enviar o ID do cliente para o servidor de autorização. Esse elemento
especifica que a Apigee precisa procurar o ID do cliente na variável de fluxo
request.formparam.client_id
. Não é possível definir ClientId
como nenhuma outra variável.
Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.client_id (um x-www-form-urlencoded e especificado no corpo da solicitação) |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: | A variável de fluxo: request.formparam.client_id |
Usado com tipos de concessão: |
Também pode ser usada com a operação GenerateAuthorizationCode. |
Elemento <Code>
<Code>request.queryparam.code</Code>
No fluxo de tipo de concessão de autorização, o cliente precisa enviar um código de autorização ao servidor de autorização (Apigee Edge). Esse elemento permite especificar onde o Edge precisa procurar o código de autorização. Por exemplo, ele pode ser enviado como um parâmetro de consulta, um cabeçalho HTTP ou um parâmetro de formulário (o padrã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 em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.auth_code
. Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.code (um x-www-form-urlencoded e especificado no corpo da solicitação) |
Presença: |
opcional |
Tipo: | String |
Valores válidos: | Qualquer variável de fluxo acessível para a política no tempo de execução |
Usado com tipos de concessão: | authorization_code |
Elemento <ExpiresIn>
<ExpiresIn>10000</ExpiresIn>
Aplica o tempo de expiração dos tokens de acesso e 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>
for definido como -1, o token ou código vai expirar de acordo com a expiração máxima do token de acesso OAuth.
Se <ExpiresIn>
não for especificado, o sistema aplicará um valor padrão configurado no nível do sistema.
O tempo de expiração também pode ser definido no tempo de execução usando um valor padrão codificado ou referir-se a uma variável de fluxo. Por exemplo, você pode armazenar um valor de expiração de token em um mapa de chave-valor, recuperá-lo, atribuí-lo a uma variável e referenciá-lo na política. Por exemplo, kvm.oauth.expires_in
.
Com o Apigee Edge for Public Cloud, o Edge mantém as entidades a seguir em cache por no mínimo 180 segundos após o acesso delas.
- Tokens de acesso do OAuth Isso significa que um token revogado pode ter êxito por até três minutos, até que o limite de cache expire.
- Entidades de serviço de gerenciamento de chaves (KMS) (apps, desenvolvedores, produtos de API).
- Atributos personalizados em tokens OAuth e entidades KMS.
A estrofe a seguir especifica também uma variável de fluxo e um valor padrão. Observe que o valor da variável de fluxo tem precedência sobre o valor padrão especificado.
<ExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </ExpiresIn>
O Edge não permite uma maneira de forçar a expiração de um token depois que ele foi criado. Se você precisar forçar a expiração de token (por exemplo, com base em uma condição), uma solução possível pode ser descrita nesta postagem da comunidade da Apigee.
Por padrão, os tokens de acesso expirados são limpos do sistema Apigee Edge automaticamente três dias após a expiração. Consulte também Como limpar tokens de acesso
Nuvem privada: para uma instalação de nuvem privada de borda, o valor padrão é definido pela propriedade conf_keymanagement_oauth_auth_code_expiry_time_in_millis
.
Para definir essa propriedade:
- Abra o arquivo
message-processor.properties
em um editor. Se o arquivo não existir, crie-o:vi /opt/apigee/customer/application/message-processor.properties
- Defina a propriedade conforme desejado:
conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
- Verifique se o arquivo de propriedades é de propriedade do usuário "apigee":
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Reinicie o processador de mensagens.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Padrão: |
Se não for especificado, o sistema aplicará um valor padrão configurado no nível do sistema. |
Presença: |
Opcional |
Tipo: | Número inteiro |
Valores válidos: |
|
Usado com tipos de concessão: |
Também usado com a operação GenerateAuthorizationCode. |
Elemento <ExternalAccessToken>
<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>
Informa ao Apigee Edge onde encontrar um token de acesso externo (um token de acesso não gerado pelo Apigee Edge).
A variável request.queryparam.external_access_token
indica que o token de acesso externo precisa estar presente como um parâmetro de consulta, como, por exemplo, ?external_access_token=12345678
. Para exigir o token de acesso externo em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.external_access_token
. Consulte também Como usar tokens OAuth de terceiros.
Elemento <ExternalAuthorization>
<ExternalAuthorization>true</ExternalAuthorization>
Se esse elemento for falso ou não estiver presente, o Edge vai validar o client_id e o client_secret normalmente em relação ao armazenamento de autorização do Apigee Edge. Use esse elemento quando quiser trabalhar com tokens OAuth de terceiros. Para detalhes sobre como usar esse elemento, consulte Como usar tokens OAuth de terceiros.
Padrão: |
falso |
Presença: |
Opcional |
Tipo: | Booleano |
Valores válidos: | verdadeiro ou falso |
Usado com tipos de concessão: |
|
Elemento <ExternalAuthorizationCode>
<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>
Informa ao Apigee Edge onde encontrar um código de autenticação externo (um código de autenticação não gerado pelo Apigee Edge).
A variável request.queryparam.external_auth_code
indica que o código de autenticação externo deve estar presente como um parâmetro de consulta, como, por exemplo, ?external_auth_code=12345678
. Para exigir o código de autenticação externo em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.external_auth_code
. Consulte também Como usar tokens OAuth de terceiros.
Elemento <ExternalRefreshToken>
<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>
Informa ao Apigee Edge onde encontrar um token de atualização externo (um token de atualização não gerado pelo Apigee Edge).
A variável request.queryparam.external_refresh_token
indica que o token de atualização externo precisa estar presente como um parâmetro de consulta, como, por exemplo, ?external_refresh_token=12345678
. Para exigir o token de atualização externo em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.external_refresh_token
. Consulte também Como usar tokens OAuth de terceiros.
Elemento <GenerateResponse>
<GenerateResponse enabled='true'/>
Se definida como true
, a política gerará e retornará uma resposta. Por exemplo, para GenerateAccessToken, a resposta pode ser como:
{ "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" : "edward@slalom.org", "token_type" : "BearerToken", "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ", "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj", "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a", "organization_name" : "cerruti", "refresh_token_expires_in" : "0", "refresh_count" : "0" }
Se false
, nenhuma resposta será enviada. Em vez disso, um conjunto de variáveis de fluxo é preenchido com valores relacionados à função da política. Por exemplo, uma variável de fluxo chamada oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code
é preenchida com o código de autenticação recém-criado. Observe que expires_in é expresso em segundos na resposta.
Padrão: |
falso |
Presença: |
Opcional |
Tipo: | string |
Valores válidos: | verdadeiro ou falso |
Usado com tipos de concessão: |
|
Elemento <GenerateErrorResponse>
<GenerateErrorResponse enabled='true'/>
Se configurada como true
, a política gerará e retornará uma resposta se o atributo ContinueOnError estiver definido como "true". Se false
(o padrão), nenhuma resposta será enviada. Em vez disso, um conjunto de variáveis de fluxo é preenchido com valores relacionados à função da política.
Padrão: |
falso |
Presença: |
Opcional |
Tipo: | string |
Valores válidos: | verdadeiro ou falso |
Usado com tipos de concessão: |
|
<GrantType>
<GrantType>request.queryparam.grant_type</GrantType>
Informa a política para encontrar o parâmetro de tipo de concessão que é transmitido em uma solicitação. De acordo com a especificação OAuth 2.0, o tipo de concessão precisa ser fornecido com solicitações de tokens 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 (padrão).
Por exemplo, request.queryparam.grant_type
indica que a senha precisa estar presente como um parâmetro de consulta, como, por exemplo, ?grant_type=password
.
Para exigir o tipo de concessão em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.grant_type
. Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.grant_type (um x-www-form-urlencoded e especificado no corpo da solicitação) |
Presença: |
Opcional |
Tipo: | string |
Valores válidos: | Uma variável, conforme explicado acima. |
Usado com tipos de concessão: |
|
Elemento <Operation>
<Operation>GenerateAuthorizationCode</Operation>
A operação do OAuth 2.0 executada pela política.
Padrão: |
Se |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: |
|
Elemento <PassWord>
<PassWord>request.queryparam.password</PassWord>
Este elemento é usado apenas com o tipo de concessão de senha. Com o tipo de concessão de senha, as credenciais de usuário (senha e nome de usuário) precisam ser disponibilizadas à política de OAuthV2. Os elementos <PassWord>
e <UserName>
são
usados para especificar variáveis em que o Edge pode encontrar esses valores. Se esses elementos não forem especificados, a política espera encontrar os valores (por padrão) nos parâmetros do formulário chamados username
e password
. Se os valores não forem encontrados, a política emitirá um erro. É possível usar os elementos <PassWord>
e <UserName>
para referir-se a qualquer variável de fluxo que contenha as credenciais.
Por exemplo, é possível transmitir a senha em uma solicitação de token usando um parâmetro de consulta e definir o elemento da seguinte maneira: <PassWord>request.queryparam.password</PassWord>
.
Para exigir a senha em um cabeçalho HTTP, defina esse valor para request.header.password
.
A política OAuthV2 não faz mais nada com esses valores de credenciais. O Edge está apenas verificando se eles estão presentes. Cabe ao desenvolvedor da API recuperar a solicitação de valores e enviá-los para um provedor de identidade antes da execução da política de geração de tokens.
Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.password (um x-www-form-urlencoded e especificado no corpo da solicitação) |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: | Qualquer variável de fluxo disponível para a política no ambiente da execução. |
Usado com tipos de concessão: | senha |
Elemento <RedirectUri>
<RedirectUri>request.queryparam.redirect_uri</RedirectUri>
Especifica onde o Edge precisa procurar o parâmetro redirect_uri
na
solicitação.
Sobre URIs de redirecionamento
Os URIs de redirecionamento são usados com os códigos de autorização e os tipos de concessão implícitos. O URI de redirecionamento informa ao servidor de autorização (Edge) para onde enviar um código de autorização (para o tipo de concessão de código de autorização) ou um token de acesso (para o tipo de concessão implícita). É importante entender quando esse parâmetro é obrigatório, quando ele é opcional e como ele é usado:
-
(obrigatório) Se um URL de callback for registrado no app de desenvolvedor associado às chaves de cliente da solicitação e se
redirect_uri
estiver presente na solicitação, os dois precisarão corresponder exatamente. Se não corresponderem, um erro será retornado. Para informações sobre como registrar apps de desenvolvedores no Edge e especificar um URL de callback, consulte Registrar apps e gerenciar chaves de API. - (opcional) Se um URL de callback estiver registrado e o
redirect_uri
estiver ausente da solicitação, o Edge redirecionará para o URL de callback registrado. - (obrigatório) Se um URL de chamada de retorno não estiver registrado, o
redirect_uri
será necessário. Observe que, nesse caso, o Edge aceita QUALQUER URL. Este caso pode apresentar um problema de segurança, e só deve ser usado com aplicativos clientes confiáveis. Se os aplicativos clientes não forem confiáveis, a prática recomendada é sempre exigir o registro de um URL de retorno de chamada.
É possível enviar esse parâmetro em um parâmetro de consulta ou em um cabeçalho. A variável request.queryparam.redirect_uri
indica que o RedirectUri precisa estar presente como um parâmetro de consulta, como, por exemplo, ?redirect_uri=login.myapp.com
. Para exigir o RedirectUri em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.redirect_uri
. Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.redirect_uri (um x-www-form-urlencoded e especificado no corpo da solicitação) |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: | Qualquer variável de fluxo acessível para a política no tempo de execução |
Usado com tipos de concessão: |
Também usado com a operação GenerateAuthorizationCode. |
Elemento <RefreshToken>
<RefreshToken>request.queryparam.refreshtoken</RefreshToken>
Ao solicitar um token de acesso usando um token de atualização, é necessário fornecer o token de atualização na solicitação. Esse elemento permite especificar onde o Edge precisa procurar o token de atualização. Por exemplo, ele pode ser enviado como um parâmetro de consulta, um cabeçalho HTTP ou um parâmetro de formulário (o padrão).
A variável request.queryparam.refreshtoken
indica que o token de atualização precisa estar presente como um parâmetro de consulta, como, por exemplo, ?refresh_token=login.myapp.com
. Para exigir ou atualizar um cabeçalho HTTP, por exemplo, defina esse valor como request.header.refresh_token
. Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.refresh_token (um x-www-form-urlencoded e especificado no corpo da solicitação) |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: | Qualquer variável de fluxo acessível para a política no tempo de execução |
Usado com tipos de concessão: |
|
Elemento <RefreshTokenExpiresIn>
<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>
Aplica o tempo de expiração 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>
for definido como -1, o token de atualização expirará de acordo com a expiração máxima do token de atualização OAuth. Se <RefreshTokenExpiresIn>
não for especificado, o sistema aplicará um valor padrão configurado no nível do sistema. Entre em contato com o suporte do Apigee Edge para mais
informações sobre as configurações padrão do sistema.
O tempo de expiração também pode ser definido no tempo de execução usando um valor padrão codificado ou referir-se a uma variável de fluxo. Por exemplo, você pode armazenar um valor de expiração de token em um mapa de chave-valor, recuperá-lo, atribuí-lo a uma variável e referenciá-lo na política. Por exemplo, kvm.oauth.expires_in
.
A estrofe a seguir especifica também uma variável de fluxo e um valor padrão. Observe que o valor da variável de fluxo tem precedência sobre o valor padrão especificado.
<RefreshTokenExpiresIn ref="kvm.oauth.expires_in"> 3600000 <!--default value in milliseconds--> </RefreshTokenExpiresIn>
Nuvem privada:para uma instalação do Edge para nuvem privada, o valor padrão
é definido pela propriedade conf_keymanagement_oauth_refresh_token_expiry_time_in_millis
.
Para definir essa propriedade:
- Abra o arquivo
message-processor.properties
em um editor. Se o arquivo não existir, crie-o:vi /opt/apigee/customer/application/message-processor.properties
- Defina a propriedade conforme desejado:
conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
- Verifique se o arquivo de propriedades é de propriedade do usuário "apigee":
chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
- Reinicie o processador de mensagens.
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Padrão: |
63072000000 ms (dois anos) (em vigor a partir de 5 de agosto de 2024) |
Presença: |
Opcional |
Tipo: | Número inteiro |
Valores válidos: |
|
Usado com tipos de concessão: |
|
Elemento <ResponseType>
<ResponseType>request.queryparam.response_type</ResponseType>
Esse elemento informa ao Edge qual tipo de concessão o app cliente está solicitando. Ela é usada apenas com o código de autorização e fluxos de tipo de concessão implícito.
Por padrão, o Edge procura o valor do tipo de resposta em um parâmetro de consulta response_type
. Se você quiser modificar esse comportamento padrão, use o elemento <ResponseType> para configurar uma variável de fluxo contendo o valor do tipo de resposta. Por exemplo, se você definir esse
elemento como request.header.response_type
, o Edge vai procurar o tipo de resposta a ser
transmitido no cabeçalho da solicitação. Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.response_type (a x-www-form-urlencoded and specified in the request body) |
Presença: |
Opcional. Use este elemento se quiser modificar o comportamento padrão. |
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ícito) |
Usado com tipos de concessão: |
|
Elemento <ReuseRefreshToken>
<ReuseRefreshToken>true</ReuseRefreshToken>
Quando definido como true
, o token de atualização existente é reutilizado até que ele expire. Se for
false
, um novo token de atualização será emitido pelo Apigee Edge quando um token de atualização válido for
apresentado.
Padrão: |
|
Presença: |
opcional |
Tipo: | boolean |
Valores válidos: |
|
Usado com tipo de concessão: |
|
Elemento <Scope>
<Scope>request.queryparam.scope</Scope>
Se esse elemento estiver presente em uma das políticas GenerateAccessToken ou GenerateAuthorizationCode, ele será usado para especificar os escopos que serão concedidos ao token ou código. Normalmente, esses valores são transmitidos à política na solicitação de um app cliente. Você pode configurar o elemento para ter uma variável de fluxo, dando a opção de escolher como os escopos são passados em uma solicitação. No exemplo a seguir, request.queryparam.scope
indica que o escopo deve estar presente como um parâmetro de consulta, por exemplo, ?scope=READ
. Para exigir o escopo em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.scope
.
Se esse elemento aparecer em uma política "VerifyAccessToken", ele será usado para especificar quais escopos a política precisa aplicar. Nesse tipo de política, o valor precisa ser um nome de escopo "codificado". Não é possível usar variáveis. Exemplo:
<Scope>A B</Scope>
Consulte também Como trabalhar com escopos do OAuth2 e Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
Sem escopo |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: |
Se usada com políticas Generate*, uma variável de fluxo. Se usadA com VerifyAccessToken, uma lista separada por espaço de nomes de escopo (strings). |
Usado com tipos de concessão: |
|
Elemento <State>
<State>request.queryparam.state</State>
Nos casos em que o app cliente precisa enviar as informações de estado para o servidor de autorização, esse elemento permite especificar onde o Edge precisa procurar os valores de estado. Por exemplo, ele pode ser enviado como um parâmetro de consulta ou em um cabeçalho HTTP. O valor do estado normalmente é 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 em um cabeçalho HTTP, por exemplo, defina esse valor como request.header.state
. Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
Sem estado |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: | Qualquer variável de fluxo acessível para a política no tempo de execução |
Usado com tipos de concessão: |
|
Elemento <StoreToken>
<StoreToken>true</StoreToken>
Defina esse elemento como true
quando o elemento <ExternalAuthorization>
for true
. O elemento <StoreToken>
instrui o Apigee Edge a
armazenar o token de acesso externo. Caso contrário, não será mantida.
Padrão: |
falso |
Presença: |
Opcional |
Tipo: | Booleano |
Valores válidos: | verdadeiro ou falso |
Usado com tipos de concessão: |
|
Elemento <SupportedGrantTypes>/<GrantType>
<SupportedGrantTypes> <GrantType>authorization_code</GrantType> <GrantType>client_credentials</GrantType> <GrantType>implicit</GrantType> <GrantType>password</GrantType> </SupportedGrantTypes>
Especifica os tipos de concessão compatíveis com um endpoint de token OAuth no Apigee Edge. Um endpoint pode aceitar vários tipos de concessão, ou seja, um único endpoint pode ser configurado para distribuir tokens de acesso para vários tipos de concessão. Para mais informações sobre endpoints, consulte Noções básicas sobre endpoints do OAuth. O tipo de concessão é transmitido em solicitações de token em um parâmetro grant_type
.
Se nenhum tipo de concessão compatível for especificado, os únicos tipos de concessão permitidos serão authorization_code
e implicit
. Veja também o elemento <GrantType>, que é um elemento de nível superior usado para especificar onde o Apigee Edge precisa procurar o parâmetro grant_type
que é transmitido em uma solicitação do cliente. O Edge vai garantir que o valor do parâmetro grant_type
corresponda a um dos tipos de concessão aceitos.
Padrão: |
authorization _code e implícito |
Presença: |
Obrigatório |
Tipo: | String |
Valores válidos: |
|
Elemento <Tokens>/<Token>
Usado com as operações ValidateToken e InvalidateToken. Consulte também Como aprovar e revogar tokens de acesso. O elemento <Token> identifica a variável do fluxo que define a origem do token a ser revogado. Se os desenvolvedores precisarem enviar tokens de acesso como parâmetros de consulta chamados 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 senha. Com o tipo de concessão de senha, as credenciais de usuário (senha e nome de usuário) precisam ser disponibilizadas à política de OAuthV2. Os elementos <PassWord>
e <UserName>
são usados para especificar variáveis em que o Edge pode encontrar esses valores. Se esses elementos não forem especificados, a política espera encontrar os valores (por padrão) nos parâmetros do formulário chamados username
e password
. Se os valores não forem encontrados, a política emitirá um erro. É possível usar os elementos <PassWord>
e <UserName>
para referir-se a qualquer variável de fluxo que contenha as credenciais.
Por exemplo, você pode passar o nome de usuário em um parâmetro de consulta e definir o elemento <UserName>
como este: <UserName>request.queryparam.username</UserName>
.
Para exigir o nome de usuário em um cabeçalho HTTP, defina esse valor como request.header.username
.
A política OAuthV2 não faz mais nada com esses valores de credenciais. O Edge está apenas verificando se eles estão presentes. Cabe ao desenvolvedor da API recuperar a solicitação de valores e enviá-los para um provedor de identidade antes da execução da política de geração de tokens.
Consulte também Como solicitar tokens de acesso e códigos de autorização.
Padrão: |
request.formparam.username (um x-www-form-urlencoded e especificado no corpo da solicitação) |
Presença: |
Opcional |
Tipo: | String |
Valores válidos: | Qualquer configuração de variável. |
Usado com tipos de concessão: | senha |
Como verificar tokens de acesso
Quando um endpoint de token é configurado para um proxy de API, uma política OAuthV2 correspondente que especifica a operação VerifyAccessToken
é anexada ao fluxo que expõe o recurso protegido.
Por exemplo, para garantir que todas as solicitações para uma API sejam autorizadas, a seguinte política impõe a verificação de token de acesso:
<OAuthV2 name="VerifyOAuthAccessToken"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
A política está anexada ao recurso de API a ser protegido. Para garantir que todas as solicitações a uma API sejam verificadas, anexe a política ao PreFlow da solicitação ProxyEndpoint da seguinte maneira:
<PreFlow> <Request> <Step><Name>VerifyOAuthAccessToken</Name></Step> </Request> </PreFlow>
Os seguintes elementos opcionais podem ser usados para substituir as definições padrão da operação VerifyAccessToken.
Nome | Descrição |
---|---|
Escopo |
Uma lista de escopos delimitada por espaço. A verificação será bem-sucedida se pelo menos um dos escopos listados estiver presente no token de acesso. Por exemplo, a política a seguir verificará o token de acesso para garantir que ela contenha pelo menos um dos escopos listados. Se READ ou WRITE estiver presente, a verificação será 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 padrão, o token de acesso será apresentado pelo aplicativo no cabeçalho HTTP de autorização, de acordo com a especificação do OAuth 2.0. Use essa configuração se espera que o token de acesso seja apresentado em um local não padrão, como um parâmetro de consulta ou um cabeçalho HTTP com um nome diferente de Authorization. |
Consulte também Como verificar tokens de acesso e Como solicitar tokens de acesso e códigos de autorização.
Como especificar locais de variáveis de solicitação
Para cada tipo de concessão, a política faz suposições sobre o local ou as informações necessárias em mensagens de solicitação. Essas suposições são baseadas na especificação do OAuth 2.0. Se os seus apps precisarem se desviar da especificação OAuth 2.0, especifique os locais esperados para cada parâmetro. Por exemplo, ao manipular um código de autorização, é possível especificar o local do código de autorização, o ID do cliente, o URI de redirecionamento e o escopo. Eles podem ser especificados como cabeçalhos HTTP, parâmetros de consulta ou parâmetros de formulário.
No exemplo abaixo, demonstramos como você pode especificar a localização dos parâmetros obrigatórios do código de autorização 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> ...
Ou, se necessário, para oferecer suporte à sua base de aplicativos cliente, você pode misturar e corresponder 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 um local por parâmetro.
Variáveis de fluxo
As variáveis de fluxo definidas nesta tabela são preenchidas quando as respectivas políticas de OAuth são executadas e, portanto, estão disponíveis para outras políticas ou aplicativos em execução no fluxo de proxy da API.
Operação VerifyAccessToken
A operação VerifyAccessToken é executada, um grande número de variáveis de fluxo é preenchido no contexto de execução do proxy. Essas variáveis fornecem propriedades relacionadas ao token de acesso, ao app do desenvolvedor, ao desenvolvedor e à empresa. Você pode usar uma política do AssignMessage ou JavaScript, por exemplo, para ler qualquer uma dessas variáveis e usá-las conforme necessário mais tarde no fluxo. Essas variáveis também podem ser úteis para fins de depuração.
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, flow.resource.name
precisa ser definido explicitamente para preencher as variações do produto de API no fluxo. Para detalhes sobre a configuração do produto, consulte Como usar a API Edge Management para publicar APIs.
Variáveis específicas de token
Variáveis | Descrição |
---|---|
organization_name |
O nome da organização em que o proxy está sendo executado. |
developer.id |
O ID do desenvolvedor associado ao app cliente registrado. |
developer.app.name |
O nome do desenvolvedor associado ao app cliente registrado. |
client_id |
O ID do cliente do aplicativo cliente registrado. |
grant_type |
O tipo de concessão associado à solicitação. |
token_type |
O tipo de token associado à solicitação. |
access_token |
O token de acesso que está sendo verificado. |
accesstoken.{custom_attribute} |
Um atributo personalizado nomeado no token de acesso. |
issued_at |
A data em que o token de acesso foi emitido, expresso no horário de era Unix em milissegundos. |
expires_in |
O prazo de validade do token de acesso. Expresso em segundos. Embora o elemento ExpiresIn defina a validade em milissegundos, nas variáveis de fluxo e resposta do token, o valor é expressado em segundos. |
status |
O status do token de acesso (por exemplo, aprovado ou revogado). |
scope |
O escopo (se houver) associado ao token de acesso. |
apiproduct.<custom_attribute_name> |
Um atributo personalizado nomeado do produto da API associado ao aplicativo cliente registrado. |
apiproduct.name |
O nome do produto da API associado ao aplicativo cliente registrado. |
revoke_reason |
(Somente híbridos da Apigee) Indica por que o token de acesso foi revogado. O valor pode ser |
Variáveis específicas do aplicativo
Essas variáveis estão relacionadas ao app do desenvolvedor associado 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: desenvolvedor |
app.appParentId |
|
app.created_by |
|
app.created_at |
|
app.last_modified_at |
|
app.last_modified_by |
|
app.{custom_attributes} |
Um atributo personalizado nomeado do app cliente registrado. |
Variáveis específicas de desenvolvedor
Se o app.appType for "Company", os atributos da empresa serão preenchidos e se app.appType for "Developer", os atributos do desenvolvedor serão preenchidos.
Variáveis | Descrição |
---|---|
Variáveis específicas de desenvolvedor | |
developer.id |
|
developer.userName |
|
developer.firstName |
|
developer.lastName |
|
developer.email |
|
developer.status |
ativo ou inativo |
developer.apps |
|
developer.created_by |
|
developer.created_at |
|
developer.last_modified_at |
|
developer.last_modified_by |
|
developer.{custom_attributes} |
Um atributo personalizado nomeado do desenvolvedor. |
Variáveis específicas da empresa
Se o app.appType for "Company", os atributos da empresa serão preenchidos e se app.appType for "Developer", os atributos do desenvolvedor serão preenchidos.
Variáveis | Descrição |
---|---|
company.id |
|
company.displayName |
|
company.apps |
|
company.appOwnerStatus |
|
company.created_by |
|
company.created_at |
|
company.last_modified_at |
|
company.last_modified_by |
|
company.{custom_attributes} |
Um atributo personalizado nomeado da empresa. |
Operação GenerateAuthorizationCode
Essas 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 ao aplicativo cliente registrado. |
scope |
O escopo opcional do OAuth transmitido na solicitação do cliente. |
client_id |
ID do cliente passado na solicitação do cliente |
Operações GenerateAccessToken e RefreshAccessToken operations
Essas variáveis são definidas quando as operações GenerateAccessToken e RefreshAccessToken são executadas com êxito. As variáveis de token de atualização não se aplicam ao fluxo de tipo de credencial do cliente.
Prefixo: oauthv2accesstoken.{policy_name}.{variable_name}
Exemplo: oauthv2accesstoken.GenerateTokenPolicy.access_token
Nome da variável | Descrição |
---|---|
access_token |
O token de acesso gerado. |
client_id |
O ID do cliente do aplicativo de desenvolvedor associado a este token. |
expires_in |
O valor de expiração do token. Consulte o elemento <ExpiresIn> para detalhes. Na resposta, expires_in é expresso em segundos. |
scope |
Lista dos escopos disponíveis configurados para o token. Consulte Como trabalhar com escopos do OAuth2. |
status |
approved ou revoked . |
token_type |
Está definida como BearerToken . |
developer.email |
O endereço de e-mail do desenvolvedor registrado que é proprietário do app de desenvolvedor associado ao token. |
organization_name |
A organização em que o proxy é executado. |
api_product_list |
Uma lista dos produtos associados ao aplicativo de desenvolvedor correspondente do token. |
refresh_count |
|
refresh_token |
O token de atualização gerado. Observe que os tokens de atualização não são gerados para o tipo de concessão de credenciais do cliente. |
refresh_token_expires_in |
A vida útil do token de atualização, em segundos. |
refresh_token_issued_at |
Esse valor de tempo é a representação de string da quantidade de carimbo de data/hora correspondente de 32 bits. Por exemplo, "Quarta-feira, 21 de agosto de 2013 19:16:47 UTC" corresponde ao valor de carimbo de data/hora 1377112607413. |
refresh_token_status |
approved ou revoked . |
GenerateAccessTokenImplicitGrant
Essas variáveis são definidas quando a operação GenerateAccessTokenImplicit é executada com êxito para o fluxo de tipo de concessão implícita.
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 expiração do token, em segundos. Consulte o elemento <ExpiresIn> para detalhes. |
Referência de erros
This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.
Runtime errors
These errors can occur when the policy executes.
Fault code | HTTP status | Cause | Thrown by operations |
---|---|---|---|
steps.oauth.v2.access_token_expired |
401 | The access token is expired. |
VerifyAccessToken |
steps.oauth.v2.access_token_not_approved |
401 | The access token was revoked. | VerifyAccessToken |
steps.oauth.v2.apiresource_doesnot_exist |
401 | The requested resource does not exist any of the API products associated with the access token. | VerifyAccessToken |
steps.oauth.v2.FailedToResolveAccessToken |
500 | The policy expected to find an access token in a variable specified in the
<AccessToken> element, but the variable could not be resolved. |
GenerateAccessToken |
steps.oauth.v2.FailedToResolveAuthorizationCode |
500 | The policy expected to find an authorization code in a variable specified in the
<Code> element, but the variable could not be resolved. |
GenerateAuthorizationCode |
steps.oauth.v2.FailedToResolveClientId |
500 | The policy expected to find the Client ID in a variable specified in the
<ClientId> element, but the variable could not be resolved. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.FailedToResolveRefreshToken |
500 | The policy expected to find a refresh token in a variable specified in the
<RefreshToken> element, but the variable could not be resolved. |
RefreshAccessToken |
steps.oauth.v2.FailedToResolveToken |
500 | The policy expected to find a token in a variable specified in the
<Tokens> element, but the variable could not be resolved. |
ValidateToken |
steps.oauth.v2.InsufficientScope |
403 | The access token presented in the request has a scope that does not match the scope specified in the verify access token policy. To learn about scope, see Working with OAuth2 scopes. | VerifyAccessToken |
steps.oauth.v2.invalid_access_token |
401 | The access token sent from the client is invalid. | VerifyAccessToken |
steps.oauth.v2.invalid_client |
401 |
This error name is returned when the Note: It is recommended that you change existing fault rule
conditions to catch both the |
GenerateAccessToken RefreshAccessToken |
steps.oauth.v2.InvalidRequest |
400 | This error name is used for multiple different kinds of errors, typically for missing
or incorrect parameters sent in the request. If <GenerateResponse> is
set to false , use fault variables (described below) to retrieve details about
the error, such as the fault name and cause. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
steps.oauth.v2.InvalidAccessToken |
401 | The authorization header does not have the word "Bearer", which is required. For
example: Authorization: Bearer your_access_token |
VerifyAccessToken |
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound |
401 |
The API proxy is not in the Product associated with the access token. Tips: Be sure that the product associated with the access token is configured correctly. For example, if you use wildcards in resource paths, be sure the wildcards are being used correctly. See Create API products for details. See also this Apigee Community post for more guidance on causes for this error. |
VerifyAccessToken |
steps.oauth.v2.InvalidClientIdentifier |
500 |
This error name is returned when the |
GenerateAccessToken |
steps.oauth.v2.InvalidParameter |
500 | The policy must specify either an access token or an authorization code, but not both. | GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.InvalidTokenType |
500 | The <Tokens>/<Token> element requires you to specify the token
type (for example, refreshtoken ). If the client passes the wrong type, this
error is thrown. |
ValidateToken InvalidateToken |
steps.oauth.v2.MissingParameter |
500 | The response type is token , but no grant types are specified. |
GenerateAuthorizationCode GenerateAccessTokenImplicitGrant |
steps.oauth.v2.UnSupportedGrantType |
500 |
The client specified a grant type that is unsupported by the policy (not listed in the <SupportedGrantTypes> element). Note: There is currently a bug where unsupported grant type errors are not thrown correctly. If an unsupported grant type error occurs, the proxy does not enter the Error Flow, as expected. |
GenerateAccessToken GenerateAuthorizationCode GenerateAccessTokenImplicitGrant RefreshAccessToken |
Deployment errors
These errors can occur when you deploy a proxy containing this policy.
Error name | Cause |
---|---|
InvalidValueForExpiresIn |
For the |
InvalidValueForRefreshTokenExpiresIn |
For the <RefreshTokenExpiresIn> element, valid values are positive
integers and -1 . |
InvalidGrantType |
An invalid grant type is specified in the <SupportedGrantTypes>
element. See the policy reference for a list of valid types. |
ExpiresInNotApplicableForOperation |
Be sure that the operations specified in the <Operations> element support expiration. For example, the VerifyToken operation does not. |
RefreshTokenExpiresInNotApplicableForOperation |
Be sure that the operations specified in the <Operations> element support refresh token expiration. For example, the VerifyToken operation does not. |
GrantTypesNotApplicableForOperation |
Be sure that the grant types specified in <SupportedGrantTypes> are supported for the specified operation. |
OperationRequired |
You must specify an operation in this policy using the Note: If the |
InvalidOperation |
You must specify a valid operation in this policy using the
Note: If the |
TokenValueRequired |
You must specify a token <Token> value in the
<Tokens> element. |
Fault variables
These variables are set when this policy triggers an error at runtime.
<GenerateResponse>
is set to
false
. If <GenerateResponse>
is
true
, the policy returns a response to the client immediately if an error occurs --
the error flow is skipped and these variables are not populated. For more information, see
What you need to
know about policy errors.Variables | Where | Example |
---|---|---|
fault.name="fault_name" |
fault_name is the name of the fault, as listed in the Runtime errors table above. The fault name is the last part of the fault code. | fault.name = "InvalidRequest" |
oauthV2.policy_name.failed |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.failed = true |
oauthV2.policy_name.fault.name |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.fault.name = InvalidRequest
Note: For the VerifyAccessToken operation, the fault name includes this suffix: |
oauthV2.policy_name.fault.cause |
policy_name is the user-specified name of the policy that threw the fault. | oauthV2.GenerateAccesstoken.cause = Required param : grant_type |
Example error response
These responses are sent back to the client if the <GenerateResponse>
element is true.
errorcode
part of the error response. Do not rely on the text in the
faultstring
, because it could change.If <GenerateResponse>
is true, the policy returns errors
in this format for operations that generate tokens and codes. For a complete list, see see
OAuth HTTP error
response reference.
{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}
If <GenerateResponse>
is true, the policy returns errors
in this format for verify and validate operations. For a complete list, see see OAuth HTTP error
response reference.
{ { "fault":{ "faultstring":"Invalid Access Token", "detail":{ "errorcode":"keymanagement.service.invalid_access_token" } } }
Example fault rule
<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>
Esquema de política
Cada tipo de política é definido por um esquema XML (.xsd
). Para referência, os esquemas de política
estão disponíveis no GitHub.
Como trabalhar com a configuração padrão do OAuth
Todas as organizações (até mesmo uma organização de avaliação sem custo financeiro) no Apigee Edge são provisionadas com um endpoint de token OAuth. O endpoint é pré-configurado com políticas no proxy de API chamado oauth. É possível começar a usar o endpoint do token assim que criar uma conta no Apigee Edge. Para detalhes, consulte Noções básicas sobre os endpoints do OAuth.
Como limpar tokens de acesso
Por padrão, os tokens OAuth2 são eliminados do sistema Apigee Edge três dias (259.200 segundos) depois que o token de acesso e o token de atualização (se houver) tiverem expirado. Em alguns casos, é possível alterar esse padrão. Por exemplo, é possível encurtar o tempo de limpeza para economizar espaço em disco se um grande número de tokens estiver sendo gerado.
Se você estiver usando o Edge for Private Cloud, poderá mudar esse padrão definindo as propriedades da organização, conforme explicado nesta seção. O período de três dias para a exclusão de tokens expirados se aplica à versão 4.19.01 e mais recentes do Edge para nuvem privada. Para versões anteriores, o intervalo de limpeza padrão é de 180 dias.
Como atualizar as configurações de limpeza da Edge Private Cloud 4.16.01 e versões mais recentes
Observação:apenas os tokens gerados após a aplicação dessas configurações são afetados. As configurações não se aplicam aos tokens gerados anteriormente.
- Abra este arquivo para edição:
/opt/apigee/customer/application/message-processor.properties
- Adicione a seguinte propriedade para definir o número de segundos a aguardar antes de excluir um token
após o vencimento:
conf_keymanagement_oauth.access.token.purge.after.seconds=<number of seconds>
- Reinicie o processador de mensagens. Exemplo:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
<ExpiresIn>
e
<RefreshTokenExpiresIn>
.
Como atualizar as configurações de limpeza da Edge Private Cloud 4.15.07
Observação: somente os tokens gerados após a aplicação dessas configurações serão afetados. As configurações não se aplicam aos tokens que foram gerados anteriormente.
-
Defina valores positivos para os atributos
<ExpiresIn>
e<RefreshTokenExpiresIn>
na política OAuthV2. Os valores estão em milissegundos. Exemplo:<ExpiresIn>1000</ExpiresIn> <RefreshTokenExpiresIn>10000</RefreshTokenExpiresIn>
-
Implante o proxy novamente.
-
Use esta API para atualizar as propriedades de eliminação de tokens da sua organização:
POST https://<host-name>/v1/organizations/<org-name>
Payload:
<Organization name="AutomationOrganization"> <Description>Desc</Description> <Properties> <Property name="keymanagement.oauth20.access.token.purge">true</Property> <Property name="keymanagement.oauth20.access.token.purge.after.seconds">120</Property> </Properties> </Organization>
-
Reinicie o processador de mensagens. Exemplo:
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Essa API define a propriedade de eliminação de tokens como "true" para a organização chamada AutomationOrganization. Nesse caso, o token de acesso será excluído do banco de dados 120 segundos após o token e o token de atualização expirarem.
Comportamento não compatível com a RFC
A política do OAuthV2 retorna uma resposta de token que contém determinadas propriedades não compatíveis com a RFC. A tabela a seguir mostra as propriedades não compatíveis retornadas pela política OAuthV2 e as propriedades compatíveis correspondentes.
O OAuthV2 retorna: | A propriedade em conformidade com a RFC é: |
---|---|
"token_type":"BearerToken" |
"token_type":"Bearer"
|
"expires_in":"3600" |
"expires_in":3600
O valor em conformidade é um número, não uma string. |
Além disso, a resposta de erro de um token de atualização expirado quando grant_type = refresh_token
é:
{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}
No entanto, a resposta compatível com RFC é:
{"error" : "invalid_grant", "error_description" :"refresh token expired"}