Esta é a documentação do Apigee Edge.
Acesse
Documentação da Apigee X. informações
O que
A política Verify API Key permite que você aplique a verificação de chaves de API no ambiente de execução, permitindo que apenas os apps com chaves de API aprovadas acessem APIs. Essa política garante que as chaves de API sejam válidas, não sejam revogadas e sejam aprovadas para consumir os recursos específicos associados aos produtos de API.
Amostras
Chave no parâmetro de consulta
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>
Neste exemplo, a política espera encontrar a chave de API em uma variável de fluxo chamada
request.queryparam.apikey. A variável request.queryparam.{name}
é uma variável de fluxo de borda padrão preenchida com o valor de um parâmetro de consulta transmitido
na solicitação do cliente.
O comando curl a seguir transmite a chave de API em um parâmetro de consulta:
curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls
Chave no cabeçalho
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>
Neste exemplo, a política espera encontrar a chave de API em uma variável de fluxo chamada
request.header.x-apikey. A variável request.header.{name}
é uma variável padrão do fluxo do Edge preenchida com o valor de um cabeçalho transmitido
na solicitação do cliente.
O cURL a seguir mostra como transmitir a chave de API em um cabeçalho:
curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"
Chave na variável
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>
A política pode referenciar qualquer variável que contenha a chave. Neste exemplo, a política extrai a chave de API de uma variável chamada requestAPIKey.key.
Você decide como essa variável é preenchida. Por exemplo, é possível usar a política Extract Variables para preencher requestAPIKey.key de um parâmetro de consulta chamado myKey, conforme mostrado abaixo:
<ExtractVariables async="false" continueOnError="false" enabled="true" name="SetAPIKeyVar">
<Source>request</Source>
<QueryParam name="myKey">
<Pattern ignoreCase="true">{key}</Pattern>
</QueryParam>
<VariablePrefix>requestAPIKey</VariablePrefix>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</ExtractVariables>
Acessar variáveis de fluxo de política
<AssignMessage async="false" continueOnError="false" enabled="true" name="accessverifyvars">
<AssignVariable>
<Name>devFirstName</Name>
<Ref>verifyapikey.verify-api-key.developer.firstName</Ref>
<Value>ErrorOnCopy</Value>
</AssignVariable>
<AssignVariable>
<Name>devLastName</Name>
<Ref>verifyapikey.verify-api-key.developer.lastName</Ref>
<Value>ErrorOnCopy</Value>
</AssignVariable>
<AssignVariable>
<Name>devEmail</Name>
<Ref>verifyapikey.verify-api-key.developer.email</Ref>
<Value>ErrorOnCopy</Value>
</AssignVariable>
<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
<AssignTo createNew="false" transport="http" type="request"/>
</AssignMessage>
O Edge preenche automaticamente um conjunto de variáveis de fluxo ao executar a chave de API Verify política para uma chave de API válida. Use essas variáveis para acessar informações como nome e ID do aplicativo e informações sobre o desenvolvedor ou empresa que o registrou. No exemplo acima, você usa a política Assign Message para acessar o nome, sobrenome e endereço de e-mail do desenvolvedor após a execução da política Verify API Key.
Todas essas variáveis incluem o prefixo a seguir:
verifyapikey.{policy_name}
Neste exemplo, o nome da política Verify API key é "verify-api-key". Portanto, você referencia
o nome do desenvolvedor que faz a solicitação acessando
a variável verifyapikey.verify-api-key.developer.firstName.
Conheça o Edge
Sobre a política de verificação de chave de API
Quando um desenvolvedor registra um app no Edge, ele gera automaticamente uma chave do cliente e par secreto. É possível ver o par da chave do cliente e do secret do app na interface do Edge ou acessá-los da API Edge.
No momento do registro do aplicativo, o desenvolvedor seleciona um ou mais produtos de API para associar ao aplicativo, sendo um produto de API um conjunto de recursos acessíveis por proxies de API. Em seguida, o desenvolvedor passa a chave de API (chave de cliente) como parte de todas as solicitações a uma API em um produto de API associado ao aplicativo. Consulte Visão geral da publicação para saber mais.
As chaves de API podem ser usadas como tokens de autenticação ou para conseguir tokens de acesso OAuth. No OAuth, as chaves de API são chamadas de "ID do cliente". Os nomes podem ser usados de forma intercambiável. Consulte Página inicial do OAuth para mais informações.
O Edge preenche automaticamente um conjunto de variáveis de fluxo ao executar a política Verify API Key. Consulte Variáveis de fluxo abaixo para mais informações.
Referência de elemento
Veja a seguir elementos e atributos que podem ser configurados com esta política:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
<DisplayName>Custom label used in UI</DisplayName>
<APIKey ref="variable_containing_api_key"/>
</VerifyAPIKey>
Atributos <VerifyAPIKey>
O exemplo a seguir mostra os atributos na tag <VerifyAPIKey>:
<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">
A tabela a seguir descreve atributos comuns a todos os elementos pai de políticas:
| Atributo | Descrição | Padrão | Presença |
|---|---|---|---|
name |
O nome interno da política. O valor do atributo 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 <APIKey>
Esse elemento especifica a variável de fluxo que contém a chave de API. Normalmente, o cliente envia a chave de API
em um parâmetro de consulta, um cabeçalho HTTP ou um parâmetro de formulário. Por exemplo, se a chave for enviada em um cabeçalho
chamado x-apikey, a chave será encontrada na variável: request.header.x-apikey
| Padrão | NA |
|---|---|
| Presença | Obrigatório |
| Tipo | String |
Atributos
A tabela a seguir descreve os atributos do elemento <APIKey>
| Atributo | Descrição | Padrão | Presença |
|---|---|---|---|
| ref |
Uma referência à variável com a chave de API. Somente um local é permitido por política. |
N/A | Obrigatório |
Exemplos
Nestes exemplos, a chave é transmitida em parâmetros e em um cabeçalho chamado x-apikey.
Como um parâmetro de consulta:
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.queryparam.x-apikey"/>
</VerifyAPIKey>
Como um cabeçalho HTTP:
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.header.x-apikey"/>
</VerifyAPIKey>
Como um parâmetro de formulário HTTP:
<VerifyAPIKey name="APIKeyVerifier">
<APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>
Esquemas
Variáveis de fluxo
Quando uma política "Verificar chave de API" é aplicada a uma chave de API válida, o Edge preenche um conjunto de fluxos variáveis. Essas variáveis estão disponíveis para políticas ou códigos executados posteriormente no fluxo e costumam ser usadas para realizar o processamento personalizado com base nos atributos da chave de API, como o nome do aplicativo, o produto de API usado para autorizar a chave ou atributos personalizados da chave de API.
A política preenche vários tipos diferentes de variáveis de fluxo, incluindo:
- Geral
- App
- Desenvolvedor
- Empresa
- Analytics
Cada tipo de variável de fluxo tem um prefixo diferente. Todas as variáveis são escalares, exceto aquelas indicadas especificamente como matrizes.
Variáveis gerais de fluxo
A tabela a seguir lista as variáveis gerais de fluxo preenchidas pela política Verify API Key. Todas essas variáveis incluem o prefixo a seguir:
verifyapikey.{policy_name}
Por exemplo: verifyapikey.{policy_name}.client_id
As variáveis disponíveis incluem:
| Variável | Descrição |
|---|---|
client_id |
A chave de cliente (também conhecida como chave de API ou de aplicativo) fornecida pelo aplicativo solicitante. |
client_secret |
O secret de cliente associado à chave de cliente. |
redirection_uris |
Qualquer URI de redirecionamento na solicitação |
developer.app.id |
O ID do aplicativo para desenvolvedor que fez a solicitação. |
developer.app.name |
O nome do aplicativo para desenvolvedor que fez a solicitação. |
developer.id |
O ID do desenvolvedor registrado como proprietário do aplicativo solicitante. |
developer.{custom_attrib_name} |
Todos os atributos personalizados derivados do perfil da chave de aplicativo. |
DisplayName |
O valor do atributo <DisplayName> da política. |
failed |
Defina como "true" quando a validação da chave de API falhar. |
{custom_app_attrib} |
Qualquer atributo personalizado derivado do perfil do aplicativo. Especifique o nome do atributo personalizado. |
apiproduct.name* |
O nome do produto de API usado para validar a solicitação. |
apiproduct.{custom_attrib_name}* |
Qualquer atributo personalizado derivado do perfil de produto de API. |
apiproduct.developer.quota.limit* |
O limite de cota definido no produto de API, se houver. |
apiproduct.developer.quota.interval* |
O intervalo de cotas definido no produto de API, se houver. |
apiproduct.developer.quota.timeunit* |
A unidade de tempo da cota definida no produto de API, se houver. |
* As variáveis de produto de API serão preenchidas automaticamente se os produtos de API forem
configurados com um ambiente, proxies e recursos válidos (derivados da
o proxy.pathsuffix). Para instruções sobre como configurar produtos de API, consulte
Usando a borda
de gerenciamento do Kubernetes para publicar APIs. |
|
Variáveis de fluxo de apps
As variáveis de fluxo a seguir com informações sobre o aplicativo são preenchidas pela política. Todas essas variáveis incluem o prefixo a seguir:
verifyapikey.{policy_name}.app.
Exemplo:
verifyapikey.{policy_name}.app.name
As variáveis disponíveis incluem:
| Variável | Descrição |
|---|---|
name |
O nome do app. |
id |
O ID do aplicativo. |
accessType |
Não utilizado pela Apigee. |
callbackUrl |
O URL de callback do aplicativo. Normalmente usado apenas para OAuth. |
DisplayName |
O nome de exibição do aplicativo. |
status |
O status do aplicativo, como "aprovado" ou "revogado". |
apiproducts |
Uma matriz com a lista de produtos de API associados ao aplicativo. |
appFamily |
Qualquer família de aplicativos que contenha o aplicativo ou "padrão". |
appParentStatus |
O status do pai do aplicativo, como "ativo" ou "inativo" |
appType |
O tipo de aplicativo, como "Empresa" ou "Desenvolvedor". |
appParentId |
O ID do aplicativo pai. |
created_at |
O carimbo de data/hora da criação do aplicativo. |
created_by |
O endereço de e-mail do desenvolvedor que criou o aplicativo. |
last_modified_at |
A data e a hora em que o aplicativo foi atualizado pela última vez. |
last_modified_by |
O endereço de e-mail do desenvolvedor que atualizou o aplicativo pela última vez. |
{app_custom_attributes} |
Qualquer atributo personalizado do aplicativo. Especifique o nome do atributo personalizado. |
Variáveis de fluxo do desenvolvedor
As variáveis de fluxo a seguir com informações sobre o desenvolvedor são preenchidas pela política. Todas essas variáveis incluem o prefixo a seguir:
verifyapikey.{policy_name}.developer
Exemplo:
verifyapikey.{policy_name}.developer.id
As variáveis disponíveis incluem:
| Variável | Descrição |
|---|---|
id |
Retorna {org_name}@@@{developer_id} |
userName |
O nome de usuário do desenvolvedor. |
firstName |
O nome do desenvolvedor. |
lastName |
O sobrenome do desenvolvedor. |
email |
O endereço de e-mail do desenvolvedor. |
status |
O status do desenvolvedor, como "ativo", "inativo" ou "login_lock". |
apps |
Uma matriz de aplicativos associados ao desenvolvedor. |
created_at |
A data e a hora da criação do desenvolvedor. |
created_by |
O endereço de e-mail do usuário que criou o desenvolvedor. |
last_modified_at |
O carimbo de data/hora em que o desenvolvedor foi modificado pela última vez. |
last_modified_by |
O endereço de e-mail do usuário que modificou o desenvolvedor. |
{developer_custom_attributes} |
Qualquer atributo personalizado de desenvolvedor. Especifique o nome do atributo personalizado. |
Company |
O nome da empresa associada ao desenvolvedor, se houver. |
Variáveis de fluxo da empresa
As variáveis de fluxo a seguir com informações sobre a empresa são preenchidas pela política. Todas essas variáveis incluem o prefixo a seguir:
verifyapikey.{policy_name}.company
Exemplo:
verifyapikey.{policy_name}.company.name
As variáveis disponíveis incluem:
| Variável | Descrição |
|---|---|
name |
O nome da empresa. |
displayName |
O nome de exibição da empresa. |
id |
O ID da empresa. |
apps |
Uma matriz com a lista de aplicativos da empresa. |
appOwnerStatus |
O status do proprietário do aplicativo, como "ativo", "inativo" ou "login_lock".
|
created_at |
O carimbo de data/hora da criação da empresa. |
created_by |
O endereço de e-mail do usuário que criou a empresa. |
last_modified_at |
O carimbo de data/hora em que a empresa foi modificada pela última vez. |
last_modified_by |
O endereço de e-mail do usuário que modificou a empresa pela última vez. |
{company_custom_attributes} |
Qualquer atributo personalizado de empresa. Especifique o nome do atributo personalizado. |
Variáveis do Analytics
As variáveis a seguir são preenchidas automaticamente no Analytics quando uma política Verify API Key é aplicada a uma chave de API válida. Essas variáveis são preenchidas apenas pela política Verify API Key e pelas políticas de OAuth.
As variáveis e os valores podem ser usados como dimensões para criar relatórios do Analytics e ter visibilidade dos padrões de consumo de desenvolvedores e aplicativos.
- apiproduct.name
- developer.app.name
- client_id
- developer.id
Referência de erros
Nesta seção, descrevemos os códigos e as mensagens de erro retornados e as variáveis de falha definidas pelo Edge quando a política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.
Erros de execução
Esses erros podem ocorrer quando a política é executada.
| Código de falha | Status HTTP | Causa |
|---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | A empresa associada ao app Developer que tem a chave de API que você está usando tem um status inativo. Quando o status de uma Empresa é definido como inativo, você não pode acessar os desenvolvedores ou apps associados a ela. Um administrador da organização pode alterar o status de uma empresa usando a API de gerenciamento. Consulte Definir o status de uma empresa. |
keymanagement.service.DeveloperStatusNotActive |
401 |
O desenvolvedor que criou o app Developer que tem a chave de API que você está usando tem um status inativo. Quando o status de um desenvolvedor de apps é definido como inativo, todos os apps Developer criados por ele são desativados. Um usuário administrador com as devidas permissões, como administrador da organização, pode alterar o status do desenvolvedor das seguintes maneiras:
|
keymanagement.service.invalid_client-app_not_approved |
401 | O app Developer associado à chave de API foi revogado. Um app revogado não pode acessar qualquer produto de API e não invocar nenhuma API gerenciada pelo Apigee Edge. Um administrador da organização pode mudar o status de um app do desenvolvedor usando a API de gerenciamento. Consulte Aprovar ou revogar o app Developer. |
oauth.v2.FailedToResolveAPIKey |
401 | A política espera encontrar a chave de API em uma variável especificada no elemento <APIKey> da política. Esse erro ocorre quando a variável esperada não existe (ela não pode ser resolvida). |
oauth.v2.InvalidApiKey |
401 | Uma chave de API foi recebida pelo Edge, mas é inválida. Quando o Edge procura a chave no banco de dados, ele deve corresponder exatamente ao em que foi enviado na solicitação. Se a API já funcionou antes, verifique se a chave não foi gerada novamente. Se a chave tiver sido gerada novamente, você verá este erro se tentar usar a chave antiga. Para mais detalhes, consulte Registrar apps e gerenciar chaves de API. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | Uma chave de API foi recebida pelo Edge e é válida. No entanto, ele não corresponde a no App do Desenvolvedor associado ao proxy de API por meio de um Produto. |
Erros de implantação
Esses erros podem ocorrer quando você implanta um proxy que contém esta política.
| Nome do erro | Causa |
|---|---|
SpecifyValueOrRefApiKey |
O elemento <APIKey> não tem um valor ou uma chave especificada. |
Variáveis de falha
Essas variáveis são definidas quando ocorre um erro de tempo de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.
| Variáveis | Onde | Exemplo |
|---|---|---|
fault.name="fault_name" |
fault_name é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha. | fault.name Matches "FailedToResolveAPIKey" |
oauthV2.policy_name.failed |
policy_name é o nome da política especificada pelo usuário que gerou a falha. | oauthV2.VK-VerifyAPIKey.failed = true |
Exemplos de respostas de erros
{
"fault":{
"faultstring":"Invalid ApiKey",
"detail":{
"errorcode":"oauth.v2.InvalidApiKey"
}
}
}
{
"fault":{
"detail":{
"errorcode":"keymanagement.service.DeveloperStatusNotActive"
},
"faultstring":"Developer Status is not Active"
}
}
Exemplo de regra de falha
<FaultRule name="FailedToResolveAPIKey">
<Step>
<Name>AM-FailedToResolveAPIKey</Name>
</Step>
<Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>