Esta página foi traduzida pela API Cloud Translation.

Política VerifyAPIKey

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 `name` pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento `<DisplayName>` para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.	N/A	Obrigatório
`continueOnError`	Defina como `false` para retornar um erro quando uma política falhar. Esse é o comportamento esperado na maioria das políticas. Defina como `true` para que a execução do fluxo continue, mesmo depois que uma política falhar.	falso	Opcional
`enabled`	Defina como `true` para aplicar a política. Defina como `false` para desativar a política. A política não será aplicada mesmo se ela permanecer anexada a um fluxo.	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

Padrão	N/A Se você omitir esse elemento, será usado o valor do atributo `name` da política.
Presença	Opcional
Tipo	String

N/A

Se você omitir esse elemento, será usado o valor do atributo name da política.

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. Observação: não use a variável `developer.app.id` para qualquer uma das finalidades a seguir: identificador da política de cotas Chaves do mapa de chave-valor (KVM, na sigla em inglês) Identificadores enviados para os destinos a serem usados na lógica de negócios de back-end Esse ID é gerado internamente pela Apigee e não tem a garantia de permanecer o mesmo ao longo do tempo. Por exemplo, a Apigee pode alterar o formato ou o comprimento dessa variável.
`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. Observação: não use a variável `developer.id` para qualquer uma das finalidades a seguir: Identificador de cota Chaves KVM Identificadores enviados para os destinos a serem usados na lógica de negócios de back-end Esse ID é gerado internamente pela Apigee e não tem a garantia de permanecer o mesmo ao longo do tempo. Por exemplo, a Apigee pode alterar o formato ou o comprimento dessa variável.
`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

Observação: se a variável de fluxo verifyapikey.{policy_name}.app.appType for "Developer", os atributos de desenvolvedor serão preenchidos. Se app.appType for "Empresa", os atributos da empresa estão preenchidos.

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

Observação: se o verifyapikey.{policy_name}.app.appType é "Company" e, em seguida, atributos estejam preenchidos. Se app.appType for "Desenvolvedor", o desenvolvedor atributos estejam preenchidos.

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. Observação: não use a variável `company.id` para qualquer uma das finalidades a seguir: Identificador de cota Chaves KVM Identificadores enviados para os destinos a serem usados na lógica de negócios de back-end Esse ID é gerado internamente pela Apigee e não tem a garantia de permanecer o mesmo ao longo do tempo. Por exemplo, a Apigee pode alterar o formato ou o comprimento dessa variável.
`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

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
`keymanagement.service.CompanyStatusNotActive`	401	The Company associated with the Developer App that has the API key you are using has an inactive status. When a Company's status is set to inactive, you cannot access the developers or apps associated with that Company. An org admin can change a Company's status using the management API. See Set the Status of a Company.
`keymanagement.service.DeveloperStatusNotActive`	401	The developer who created the Developer App that has the API key you are using has an inactive status. When an App Developer's status is set to inactive, any Developer Apps created by that developer are deactivated. An admin user with appropriate permissions (such as Organization Administrator) can change a developer's status in the following ways: Management API: Set Developer Status Management UI: In Register app developers, see the instructions for deactivating (and activating) a developer.
`keymanagement.service.invalid_client-app_not_approved`	401	The Developer App associated with the API key is revoked. A revoked app cannot access any API products and cannot invoke any API managed by Apigee Edge. An org admin can change the status of a Developer App using the management API. See Approve or Revoke Developer App.
`oauth.v2.FailedToResolveAPIKey`	401	The policy expects to find the API key in a variable that is specified in the policy's <APIKey> element. This error arises when the expected variable does not exist (it cannot be resolved).
`oauth.v2.InvalidApiKey`	401	An API key was received by Edge, but it is invalid. When Edge looks up the key in its database, it must exactly match the on that was sent in the request. If the API worked previously, make sure the key was not regenerated. If the key was regenerated, you will see this error if you try to use the old key. For details, see Register apps and manage API keys.
`oauth.v2.InvalidApiKeyForGivenResource`	401	An API key was received by Edge, and it is valid; however, it does not match an approved key in the Developer App associated with your API proxy through a Product.

Note: Currently Edge does not report the ApiKeyNotApproved error accurately. Instead, if a key is not approved (its status is set to "revoked" or "pending"), you will get the FailedToResolveAPIKey error instead. For more information and a possible workaround, see this post on the Apigee Community.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name	Cause
`SpecifyValueOrRefApiKey`	The `<APIKey>` element does not have a value or key specified.

Fault variables

These variables are set when a runtime error occurs. 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 Matches "FailedToResolveAPIKey"`
`oauthV2.policy_name.failed`	`policy_name` is the user-specified name of the policy that threw the fault.	`oauthV2.VK-VerifyAPIKey.failed = true`

Example error responses

Note: For error handling, the best practice is to trap the errorcode part of the error response. Do not rely on the text in the faultstring, because it could change.

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}

{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Example fault rule

<FaultRule name="FailedToResolveAPIKey">
    <Step>
        <Name>AM-FailedToResolveAPIKey</Name>
    </Step>
    <Condition>(fault.name Matches "FailedToResolveAPIKey") </Condition>
</FaultRule>

Política VerifyAPIKey

O que

Amostras

Chave no parâmetro de consulta

Chave no cabeçalho

Chave na variável

Acessar variáveis de fluxo de política

Conheça o Edge

Sobre a política de verificação de chave de API

Referência de elemento

Atributos <VerifyAPIKey>

Elemento <DisplayName>

Elemento <APIKey>

Atributos

Exemplos

Esquemas

Variáveis de fluxo

Variáveis gerais de fluxo

Variáveis de fluxo de apps

Variáveis de fluxo do desenvolvedor

Variáveis de fluxo da empresa

Variáveis do Analytics

Referência de erros

Runtime errors

Deployment errors

Fault variables

Example error responses

Example fault rule

Temas relacionados