Criterio VerificationAPIKey

Stai visualizzando la documentazione di Apigee Edge.
Vai alla documentazione di Apigee X.
informazioni

Cosa

Il criterio Verifica chiave API consente di applicare la verifica delle chiavi API in fase di runtime, consentendo solo alle app con chiavi API approvate di accedere alle API. Questo criterio garantisce che le chiavi API siano valide, non siano state revocate e che siano approvate per utilizzare le risorse specifiche associate ai tuoi prodotti API.

Samples

Chiave nel parametro di query

<VerifyAPIKey name="APIKeyVerifier">
    <APIKey ref="request.queryparam.apikey" />
</VerifyAPIKey>

In questo esempio, il criterio prevede di trovare la chiave API in una variabile di flusso denominata request.queryparam.apikey. La variabile request.queryparam.{name} è una variabile di flusso perimetrale standard che viene compilata con il valore di un parametro di query passato nella richiesta del client.

Il seguente comando curl passa la chiave API in un parametro di query:

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

Chiave nell'intestazione

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

In questo esempio, il criterio prevede di trovare la chiave API in una variabile di flusso denominata request.header.x-apikey. La variabile request.header.{name} è una variabile di flusso perimetrale standard che viene compilata con il valore di un'intestazione passata nella richiesta del client.

Il seguente cURL mostra come passare la chiave API in un'intestazione:

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

Chiave nella variabile

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

Il criterio può fare riferimento a qualsiasi variabile contenente la chiave. Il criterio in questo esempio estrae la chiave API da una variabile denominata requestAPIKey.key.

La modalità di compilazione della variabile spetta a te. Ad esempio, puoi utilizzare il criterio Estrai variabili per compilare requestAPIKey.key da un parametro di query denominato myKey, come mostrato di seguito:

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

Variabili di flusso dei criteri di accesso

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

Edge compila automaticamente un insieme di variabili di flusso durante l'esecuzione del criterio di verifica della chiave API per una chiave API valida. Puoi utilizzare queste variabili per accedere a informazioni quali nome e ID dell'app e informazioni sullo sviluppatore o sull'azienda che l'ha registrata. Nell'esempio precedente, il criterio Assegna messaggio viene utilizzato per accedere al nome, al cognome e all'indirizzo email dello sviluppatore dopo l'esecuzione della verifica della chiave API.

Queste variabili sono tutte precedute da:

verifyapikey.{policy_name}

In questo esempio, il nome del criterio di verifica della chiave API è "verify-api-key". Di conseguenza, devi fare riferimento al nome dello sviluppatore che effettua la richiesta accedendo alla variabile verifyapikey.verify-api-key.developer.firstName..

Scopri Edge


Informazioni sul criterio di verifica della chiave API

Quando uno sviluppatore registra un'app su Edge, Edge genera automaticamente una coppia chiave e secret dell'utente. Puoi vedere la coppia chiave e secret dell'app nell'interfaccia utente Edge o accedervi dall'API Edge.

Al momento della registrazione dell'app, lo sviluppatore seleziona uno o più prodotti API da associare all'app. Un prodotto API è una raccolta di risorse accessibili tramite proxy API. Lo sviluppatore passa quindi la chiave API (chiave utente) come parte di ogni richiesta a un'API in un prodotto API associato all'app. Per saperne di più, consulta la Panoramica della pubblicazione.

Le chiavi API possono essere utilizzate come token di autenticazione o per ottenere token di accesso OAuth. In OAuth, le chiavi API sono chiamate "ID client". I nomi possono essere utilizzati in modo intercambiabile. Per ulteriori informazioni, vedi Home page OAuth.

Edge compila automaticamente un insieme di variabili di flusso durante l'esecuzione del criterio di verifica della chiave API. Per ulteriori informazioni, consulta la sezione Variabili di flusso di seguito.

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare su questo criterio:

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

Attributi <VerifyAPIKey>

L'esempio seguente mostra gli attributi nel tag <VerifyAPIKey>:

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

The following table describes attributes that are common to all policy parent elements:

Attribute Description Default Presence
name

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

N/A Required
continueOnError

Set to false to return an error when a policy fails. This is expected behavior for most policies.

Set to true to have flow execution continue even after a policy fails.

false Optional
enabled

Set to true to enforce the policy.

Set to false to turn off the policy. The policy will not be enforced even if it remains attached to a flow.

true Optional
async

This attribute is deprecated.

false Deprecated

<DisplayName> element

Use in addition to the name attribute to label the policy in the management UI proxy editor with a different, natural-language name.

<DisplayName>Policy Display Name</DisplayName>
Default

N/A

If you omit this element, the value of the policy's name attribute is used.

Presence Optional
Type String

Elemento <APIKey>

Questo elemento specifica la variabile di flusso che contiene la chiave API. In genere, il client invia la chiave API in un parametro di ricerca, in un'intestazione HTTP o in un parametro di modulo. Ad esempio, se la chiave viene inviata in un'intestazione denominata x-apikey, verrà trovata nella variabile: request.header.x-apikey

Predefinito NA
Presenza Obbligatorie
Tipo Stringa

Attributi

La tabella seguente descrive gli attributi dell'elemento <APIKey>

Attributo Descrizione Predefinito Presenza
rif

Un riferimento alla variabile che contiene la chiave API. È consentita una sola località per criterio.

N/A Obbligatorie

Esempi

In questi esempi, la chiave viene trasferita nei parametri e in un'intestazione chiamata x-apikey.

Come parametro di ricerca:

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

Come intestazione HTTP:

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

Come parametro del modulo HTTP:

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

Schemi

Variabili di flusso

Quando un criterio di verifica chiave API viene applicato a una chiave API valida, Edge compila un insieme di variabili di flusso. Queste variabili sono disponibili per i criteri o il codice eseguiti in un secondo momento nel flusso e vengono spesso utilizzate per eseguire l'elaborazione personalizzata in base agli attributi della chiave API come il nome dell'app, il prodotto API utilizzato per autorizzare la chiave o gli attributi personalizzati della chiave API.

Il criterio compila diversi tipi di variabili di flusso, tra cui:

  • Generale
  • App
  • Sviluppatore
  • Società
  • Analytics

Ogni tipo di variabile di flusso ha un prefisso diverso. Tutte le variabili sono scalari tranne quelle indicate specificamente come array.

Variabili di flusso generali

La seguente tabella elenca le variabili di flusso generali compilate dal criterio di verifica della chiave API. Queste variabili sono tutte precedute da:

verifyapikey.{policy_name}

Ad esempio: verifyapikey.{policy_name}.client_id

Le variabili disponibili includono:

Variabile Descrizione
client_id La chiave utente (nota anche come chiave API o chiave dell'app) fornita dall'app richiedente.
client_secret Segreto utente associato alla chiave utente.
redirection_uris Eventuali URI di reindirizzamento nella richiesta.
developer.app.id

L'ID dell'app dello sviluppatore che effettua la richiesta.

developer.app.name Il nome dell'app dello sviluppatore che effettua la richiesta.
developer.id

L'ID dello sviluppatore registrato come proprietario dell'app richiedente.

developer.{custom_attrib_name} Qualsiasi attributo personalizzato derivato dal profilo della chiave dell'app.
DisplayName Il valore dell'attributo <DisplayName> del criterio.
failed Impostalo su "true" quando la convalida della chiave API non va a buon fine.
{custom_app_attrib} Qualsiasi attributo personalizzato derivato dal profilo dell'app. Specifica il nome dell'attributo personalizzato.
apiproduct.name* Il nome del prodotto API utilizzato per convalidare la richiesta.
apiproduct.{custom_attrib_name}* Qualsiasi attributo personalizzato derivato dal profilo del prodotto API.
apiproduct.developer.quota.limit* Il limite di quota impostato per il prodotto API, se presente.
apiproduct.developer.quota.interval* L'intervallo di quota impostato sul prodotto API, se presente.
apiproduct.developer.quota.timeunit* L'unità di tempo della quota impostata sul prodotto API, se presente.
* Le variabili dei prodotti API vengono compilate automaticamente se i prodotti API sono configurati con un ambiente, proxy e risorse validi (derivati da proxy.pathsuffix). Per istruzioni sulla configurazione dei prodotti API, consulta Utilizzo dell'API di gestione perimetrale per pubblicare le API.

Variabili di flusso dell'app

Le seguenti variabili di flusso contenenti informazioni sull'app vengono compilate dal criterio. Queste variabili sono tutte precedute da:

verifyapikey.{policy_name}.app.

Ad esempio:

verifyapikey.{policy_name}.app.name

Le variabili disponibili includono:

Variabile Descrizione
name Il nome dell'app.
id L'ID dell'app.
accessType Non utilizzato da Apigee.
callbackUrl L'URL di callback dell'app. In genere viene utilizzato solo per OAuth.
DisplayName Il nome visualizzato dell'app.
status Lo stato dell'app, ad esempio, "approvata" o "revocata".
apiproducts Un array contenente l'elenco dei prodotti API associati all'app.
appFamily Qualsiasi famiglia di app contenente l'app o "predefinita".
appParentStatus Lo stato dell'app principale, ad esempio "attiva" o "inattiva"
appType Il tipo di app, come "Società" o "Sviluppatore".
appParentId L'ID dell'app principale.
created_at Il timestamp di data/ora di creazione dell'app.
created_by L'indirizzo email dello sviluppatore che ha creato l'app.
last_modified_at Il timestamp dell'ultimo aggiornamento dell'app.
last_modified_by L'indirizzo email dello sviluppatore che ha aggiornato l'app per l'ultima volta.
{app_custom_attributes} Qualsiasi attributo personalizzato dell'app. Specifica il nome dell'attributo personalizzato.

Variabili di flusso sviluppatore

Le seguenti variabili di flusso contenenti informazioni sullo sviluppatore sono completate dal criterio. Queste variabili sono tutte precedute da:

verifyapikey.{policy_name}.developer

Ad esempio:

verifyapikey.{policy_name}.developer.id

Le variabili disponibili includono:

Variabile Descrizione
id Restituisce {org_name}@@{developer_id}
userName Il nome utente dello sviluppatore.
firstName Il nome dello sviluppatore.
lastName Il cognome dello sviluppatore.
email L'indirizzo email dello sviluppatore.
status Lo stato dello sviluppatore, ad esempio attivo, non attivo o login_lock.
apps Un array di app associate allo sviluppatore.
created_at Il timestamp di data/ora di creazione dello sviluppatore.
created_by L'indirizzo email dell'utente che ha creato lo sviluppatore.
last_modified_at Il timestamp dell'ultima modifica dello sviluppatore.
last_modified_by L'indirizzo email dell'utente che ha modificato lo sviluppatore.
{developer_custom_attributes} Qualsiasi attributo sviluppatore personalizzato. Specifica il nome dell'attributo personalizzato.
Company Il nome dell'azienda, se presente, associato allo sviluppatore.

Variabili di flusso aziendale

Le seguenti variabili di flusso contenenti informazioni sull'azienda sono completate dal criterio. Queste variabili sono tutte precedute da:

verifyapikey.{policy_name}.company

Ad esempio:

verifyapikey.{policy_name}.company.name

Le variabili disponibili includono:

Variabile Descrizione
name Il nome dell'azienda.
displayName Il nome visualizzato dell'azienda.
id

L'ID dell'azienda.

apps Un array contenente l'elenco delle app aziendali.
appOwnerStatus
Lo stato del proprietario dell'app, ovvero attivo, non attivo o login_lock.
created_at Data e ora della creazione dell'azienda.
created_by L'indirizzo email dell'utente che ha creato l'azienda.
last_modified_at Il timestamp dell'ultima modifica dell'azienda.
last_modified_by L'indirizzo email dell'utente che ha modificato l'azienda per ultimo.
{company_custom_attributes} Qualsiasi attributo aziendale personalizzato. Specifica il nome dell'attributo personalizzato.

Variabili di Analytics

Le seguenti variabili vengono compilate automaticamente in Analytics quando viene applicato un criterio di verifica della chiave API per una chiave API valida. Queste variabili vengono compilate solo dal criterio di Verifica chiave API e dai criteri OAuth.

Le variabili e i valori possono essere utilizzati come dimensioni per creare report di Analytics in modo da ottenere visibilità sui modelli di consumo da parte di sviluppatori e app.

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

Messaggi di errore

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:

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.

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

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

Argomenti correlati