Política VerifyAPIKey

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

Veja a documentação do Apigee Edge.

Vista geral

A política de chave da API de validação permite-lhe aplicar a validação de chaves da API em tempo de execução, permitindo que apenas as apps com chaves da API aprovadas acedam às suas APIs. Esta política garante que as chaves da API são válidas, não foram revogadas e estão aprovadas para consumir os recursos específicos associados aos seus produtos de API.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Para ver um tutorial que mostra como criar um proxy de API que usa a política Verify API Key, consulte o artigo Proteja uma API exigindo chaves 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 da API numa variável de fluxo denominada request.queryparam.apikey. A variável request.queryparam.{name} é uma variável de fluxo do Apigee padrão preenchida com o valor de um parâmetro de consulta transmitido no pedido do cliente.

O comando curl seguinte transmite a chave da API num parâmetro de consulta:

curl http://myorg-test.apigee.net/mocktarget?apikey=IEYRtW2cb7A5Gs54A1wKElECBL65GVls

Embora seja permitido, geralmente, é uma má prática transmitir a chave da API num parâmetro de consulta. O motivo é que os parâmetros de consulta podem aparecer no histórico do navegador e nos registos de rede, o que representa um possível risco de segurança. Uma prática melhor é colocar a chave da API num cabeçalho, que não aparece nos ficheiros de registo. Veja o exemplo "KEY IN HEADER" no separador seguinte.

Chave no cabeçalho

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.header.x-apikey" />
</VerifyAPIKey>

Neste exemplo, a política espera encontrar a chave da API numa variável de fluxo denominada request.header.x-apikey. A variável request.header.{name} é uma variável de fluxo do Apigee padrão que é preenchida com o valor de um cabeçalho transmitido no pedido do cliente.

O cURL seguinte mostra como transmitir a chave da API num cabeçalho:

curl "http://myorg-test.apigee.net/mocktarget" -H "x-apikey:IEYRtW2cb7A5Gs54A1wKElECBL65GVls"

É uma boa prática transmitir a chave da API num cabeçalho em vez de num parâmetro de consulta. Isto deve-se ao facto de os cabeçalhos não aparecerem no histórico do navegador nem nos registos de rede, o que pode representar um possível risco de segurança.

Chave na variável

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="requestAPIKey.key"/>
</VerifyAPIKey>

A política pode fazer referência a qualquer variável que contenha a chave. A política neste exemplo extrai a chave da API de uma variável denominada requestAPIKey.key.

A forma como essa variável é preenchida depende de si. Por exemplo, pode usar a política Extract Variables para preencher requestAPIKey.key a partir de um parâmetro de consulta denominado 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>

Variáveis de fluxo da política de acesso

<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 Apigee preenche automaticamente um conjunto de variáveis de fluxo quando executa a política Verify API Key para uma chave da API válida. Pode usar estas variáveis para aceder a informações como o nome da app, o ID da app e informações sobre o programador ou a empresa que registou a app. No exemplo acima, usa a política de atribuição de mensagens para aceder ao nome próprio, apelido e endereço de email do programador após a execução da API Verify.

Todas estas variáveis têm o prefixo:

verifyapikey.{policy_name}

Neste exemplo, o nome da política da API Verify é "verify-api-key". Por conseguinte, faz referência ao nome próprio do programador que está a fazer o pedido acedendo à variável verifyapikey.verify-api-key.developer.firstName.

Aprenda a usar o Apigee

Exemplo: Aprenda com a prática!
O exemplo Proteja o proxy com uma chave da API protege um proxy da API com uma chave da API e o exemplo Remova o parâmetro de consulta apikey mostra como remover a chave da API do pedido para impedir que seja transmitida ao destino de back-end (uma prática recomendada). Basta clonar o repositório e seguir as instruções nos ficheiros README.

---

Acerca da política de validação da chave da API

Quando um programador regista uma app no Apigee, o Apigee gera automaticamente um par de chave e segredo do consumidor. Pode ver o par de chave secreta e chave do consumidor da app na IU do Apigee ou aceder a eles a partir da API Apigee.

Nota: as chaves da API têm vários nomes. Pode vê-los referidos como "chaves de API", "chaves de apps" e "chaves de consumidor". Todos estes nomes são sinónimos.

No momento do registo da app, o programador seleciona um ou mais produtos de API para associar à app, em que um produto de API é uma coleção de recursos acessíveis através de proxies de API. Em seguida, o programador transmite a chave da API (chave do consumidor) como parte de cada pedido a uma API num produto de API associado à app. Consulte a vista geral da publicação para mais informações.

As chaves de API podem ser usadas como tokens de autenticação ou para obter tokens de acesso OAuth. No OAuth, as chaves de API são denominadas "ID de cliente". Os nomes podem ser usados de forma intercambiável. Para mais informações, consulte a secção Página inicial do OAuth.

O Apigee preenche automaticamente um conjunto de variáveis de fluxo quando executa a política Verify API Key. Consulte Variáveis de fluxo abaixo para mais informações.

Referência do elemento

Seguem-se os elementos e os atributos que pode configurar nesta 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"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

Atributos <VerifyAPIKey>

O exemplo seguinte mostra os atributos na etiqueta <VerifyAPIKey>:

<VerifyAPIKey async="false" continueOnError="false" enabled="true" name="Verify-API-Key-1">

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Atributo	Descrição	Predefinição	Presença
name	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hífenes, sublinhados e pontos finais. Este valor não pode exceder 255 carateres. Opcionalmente, use o elemento <DisplayName> para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.	N/A	Obrigatória
continueOnError	Definido como false para devolver um erro quando uma política falha. Este comportamento é o esperado para a maioria das políticas. Definido como true para que a execução do fluxo continue mesmo depois de uma política falhar. Veja também: As regras de falhas são acionadas APENAS num estado de erro (acerca de continueOnError) Processar falhas no fluxo atual	falso	Opcional
enabled	Defina como true para aplicar a política. Defina como false para desativar a política. A política não é aplicada, mesmo que permaneça associada a um fluxo.	verdadeiro	Opcional
async	Este atributo foi descontinuado.	falso	Descontinuado

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>

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

Elemento <APIKey>

Este elemento especifica a variável de fluxo que contém a chave da API. Normalmente, o cliente envia a chave da API num parâmetro de consulta, num cabeçalho HTTP ou num parâmetro de formulário. Por exemplo, se a chave for enviada num cabeçalho denominado x-apikey, a chave é encontrada na variável: request.header.x-apikey

Predefinição	NA
Presença	Obrigatória
Tipo	String

Atributos

A tabela seguinte descreve os atributos do elemento <APIKey>

Atributo	Descrição	Predefinição	Presença
ref	Uma referência à variável que contém a chave da API. Só é permitida uma localização por política.	N/A	Obrigatória

É recomendável transmitir a chave da API num cabeçalho ou num parâmetro de formulário, em vez de num parâmetro de consulta. Isto deve-se ao facto de os parâmetros de consulta poderem aparecer nos históricos do navegador e nos registos de rede, o que pode representar um possível risco de segurança.

Exemplos

Nestes exemplos, a chave é transmitida em parâmetros e num cabeçalho denominado 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 parâmetro de formulário HTTP:

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.formparam.x-apikey"/>
</VerifyAPIKey>

Elemento <CacheExpiryInSeconds>

Este elemento aplica o TTL na cache, o que permite a personalização do período de tempo para a expiração do token de acesso em cache. O intervalo suportado é entre 1 e 180 segundos. Pode fornecer uma variável de fluxo e uma variável predefinida. Se for fornecido, o valor da variável de fluxo tem precedência sobre o valor predefinido especificado.

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

Nota: o desempenho diminui quando o intervalo de colocação em cache é reduzido.

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

Atributos

A tabela seguinte descreve os atributos do elemento <CacheExpiryInSeconds>

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

Esquemas

Exemplo: consulte os exemplos do nosso repositório do GitHub para ver os esquemas mais recentes.

Variáveis de fluxo

Quando uma política de chave da API de validação é aplicada a uma chave da API válida, o Apigee preenche um conjunto de variáveis de fluxo. Estas variáveis estão disponíveis para políticas ou código executado posteriormente no fluxo e são frequentemente usadas para realizar processamento personalizado com base em atributos da chave de API, como o nome da app, 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
• Programador
• Google Analytics
• Rentabilização

Cada tipo de variável de fluxo tem um prefixo diferente. Todas as variáveis são escalares, exceto as que são especificamente indicadas como matrizes.

Variáveis de fluxo gerais

A tabela seguinte apresenta as variáveis de fluxo gerais preenchidas pela política de chave da API Verify. Todas estas variáveis têm o prefixo:

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 consumidor (também conhecida como chave da API ou chave da app) fornecida pela app que está a fazer o pedido.
client_secret	O segredo do consumidor associado à chave de consumidor.
redirection_uris	Todos os URIs de redirecionamento no pedido.
developer.app.id	O ID do programador ou da app do AppGroup que está a fazer o pedido. Nota: não use a variável developer.app.id para nenhum dos seguintes fins: identificador da Política de Quotas Chaves do mapa de chaves-valores (KVM) Identificadores enviados para alvos para serem usados na lógica empresarial de back-end Este ID é gerado internamente pelo Apigee e não é garantido que permaneça o mesmo ao longo do tempo. Por exemplo, o Apigee pode alterar o formato ou o comprimento desta variável.
developer.app.name	O nome da app do programador ou da app do AppGroup que está a fazer o pedido.
developer.id	O ID do programador ou do AppGroup registado como proprietário da app que está a fazer o pedido. Nota: não use a variável developer.id para nenhum dos seguintes fins: Identificador de quota Teclas KVM Identificadores enviados para alvos para serem usados na lógica empresarial de back-end Este ID é gerado internamente pelo Apigee e não é garantido que permaneça o mesmo ao longo do tempo. Por exemplo, o Apigee pode alterar o formato ou o comprimento desta variável.
developer.{custom_attrib_name}	Quaisquer atributos personalizados derivados do perfil da chave da app.
DisplayName	O valor do atributo <DisplayName> da política.
failed	Definido como "true" quando a validação da chave da API falha.
{custom_app_attrib}	Qualquer atributo personalizado derivado do perfil da app. Especifique o nome do atributo personalizado.
apiproduct.name*	O nome do produto API usado para validar o pedido.
apiproduct.{custom_attrib_name}*	Qualquer atributo personalizado derivado do perfil do produto da API.
apiproduct.developer.quota.limit*	O limite da quota definido no produto da API, se existir.
apiproduct.developer.quota.interval*	O intervalo de quota definido no produto da API, se existir.
apiproduct.developer.quota.timeunit*	A unidade de tempo da quota definida no produto da API, se existir.
* As variáveis de produtos de API são preenchidas automaticamente se os produtos de API estiverem configurados com um ambiente, proxies e recursos válidos (derivados do proxy.pathsuffix). Para obter instruções sobre a configuração de produtos de API, consulte Gerir produtos de API.

Variáveis do fluxo de apps

As seguintes variáveis de fluxo que contêm informações sobre a app são preenchidas pela política. Todas estas variáveis têm o prefixo:

verifyapikey.{policy_name}.app.

Por exemplo:

verifyapikey.{policy_name}.app.name

As variáveis disponíveis incluem:

Variável	Descrição
name	O nome da app.
id	O ID da app.
accessType	Não usado pelo Apigee.
callbackUrl	O URL de retorno de chamada da app. Normalmente, usado apenas para OAuth.
DisplayName	O nome a apresentar da app.
status	O estado da app, como "aprovada" ou "revogada".
apiproducts	Uma matriz que contém a lista de produtos de API associados à app.
appFamily	Qualquer família de apps que contenha a app ou "predefinição".
appParentStatus	O estado do elemento principal da app, como "ativo" ou "inativo"
appType	O tipo de app como "Programador".
appParentId	O ID da app principal.
created_at	A data/hora em que a app foi criada.
created_by	O endereço de email do programador que criou a app.
last_modified_at	A data/hora em que a app foi atualizada pela última vez.
last_modified_by	O endereço de email do programador que atualizou a app pela última vez.
{app_custom_attributes}	Qualquer atributo de app personalizada. Especifique o nome do atributo personalizado.

Variáveis de fluxo do grupo de apps

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

Todas estas variáveis têm o prefixo:

verifyapikey.{policy_name}.appgroup.

Por exemplo:

verifyapikey.{policy_name}.appgroup.name

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

As variáveis disponíveis incluem:

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

Variáveis do fluxo de programador

As seguintes variáveis de fluxo que contêm informações sobre o programador são preenchidas pela política. Todas estas variáveis têm o prefixo:

verifyapikey.{policy_name}.developer

Por exemplo:

verifyapikey.{policy_name}.developer.id

As variáveis disponíveis incluem:

Variável	Descrição
id	Devolve {org_name}@@@{developer_id}
userName	O nome de utilizador do programador.
firstName	O nome próprio do programador.
lastName	O apelido do programador.
email	O endereço de email do programador.
status	O estado do programador, como ativo, inativo ou login_lock.
apps	Uma matriz de apps associadas ao programador. Nota: o acesso a esta variável resulta numa latência elevada quando o número de apps é superior a 10.
created_at	A data/hora de criação do programador.
created_by	O endereço de email do utilizador que criou o programador.
last_modified_at	A data/hora em que o programador foi modificado pela última vez.
last_modified_by	O endereço de email do utilizador que modificou o programador.
{developer_custom_attributes}	Qualquer atributo de programador personalizado. Especifique o nome do atributo personalizado.

Variáveis do Analytics

As seguintes variáveis são preenchidas automaticamente no Analytics quando uma política de chave da API de validação é aplicada a uma chave da API válida. Estas variáveis só são preenchidas pela política de chave da API Verify e pelas políticas OAuth.

As variáveis e os valores podem ser usados como dimensões para criar relatórios do Analytics e obter visibilidade dos padrões de consumo por parte dos programadores e das apps.

• apiproduct.name
• developer.app.name
• client_id
• developer.id

Variáveis do fluxo de rentabilização

Após a autenticação do utilizador, a política VerifyAPIKey verifica todos os planos tarifários publicados para determinar qual, se existir, está ativo com base nas respetivas horas de ativação e expiração. Se for encontrado um plano de tarifas publicado ativo, as seguintes variáveis de fluxo são preenchidas:

Variável	Descrição
mint.mintng_is_apiproduct_monetized	true se for encontrado um plano de tarifas publicado ativo.
mint.mintng_rate_plan_id	ID do plano tarifário.
mint.rateplan_end_time_ms	Hora de validade do plano tarifário. Por exemplo: 1619433556408
mint.rateplan_start_time_ms	Hora de ativação do plano tarifário. Por exemplo: 1618433956209

Referência de erro

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa 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.consumer_key_missing_api_product_association	400	A credencial do aplicativo não tem uma associação do produto da API. Associe o aplicativo da chave a um produto de API. Isso se aplica a todos os tipos de aplicativos, como apps de desenvolvedores e do AppGroup.
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: API Apigee: Definir o status de desenvolvedor IU da Apigee: em Registrar desenvolvedores de apps, consulte as instruções para desativar (e ativar) um desenvolvedor.
keymanagement.service.invalid_client-app_not_approved	401	O app Developer associado à chave de API foi revogado. Um app revogado não pode acessar nenhum produto de API e não pode invocar qualquer API gerenciada pela Apigee. Um administrador da organização pode alterar o status de um app Developer usando a API Apigee. Consulte Gerar par de chaves ou Atualizar status do app do desenvolvedor.
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 pela Apigee, mas é inválida. Quando a Apigee procura a chave no banco de dados, ela precisa corresponder exatamente àquela que foi enviada 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 Como controlar o acesso às suas APIs registrando aplicativos.
oauth.v2.InvalidApiKeyForGivenResource	401	Uma chave de API foi recebida pela Apigee e é válida; no entanto, ela não corresponde a uma chave aprovada no app Developer associado ao seu proxy de API por meio de um produto.

Observação: atualmente, a Apigee não relata o erro ApiKeyNotApproved com precisão. Em vez disso, se uma chave não for aprovada (o status dela está definido como revoked ou pending), você receberá o erro FailedToResolveAPIKey. Para mais informações e uma possível solução alternativa, consulte Verificar se a chave da API não informa a chave de API não aprovada.

Erros na 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

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

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