Criterio VerifyAPIKey

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

icona delle norme

Panoramica

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

Questo criterio è un criterio estensibile e il suo utilizzo potrebbe comportare implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni per l'utilizzo, consulta Tipi di criteri.

Per un tutorial che mostra come creare un proxy API che utilizza il criterio Verifica chiave API, consulta Proteggere un'API richiedendo le chiavi API.

Esempi

Chiave nel parametro di query

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

In questo esempio, il criterio si aspetta di trovare la chiave API in una variabile di flusso denominata request.queryparam.apikey. La variabile request.queryparam.{name} è una variabile di flusso Apigee 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

Inserisci la chiave nell'intestazione

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

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

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

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

Inserisci la 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 dipende da te. Ad esempio, puoi utilizzare il criterio Estrazione 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 del 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>

Apigee compila automaticamente un insieme di variabili di flusso quando esegue il criterio Verifica chiave API per una chiave API valida. Puoi utilizzare queste variabili per accedere a informazioni quali il nome dell'app, l'ID app e informazioni sullo sviluppatore o sull'azienda che ha registrato l'app. Nell'esempio riportato sopra, utilizzi il criterio Assegna messaggio per accedere al nome, al cognome e all'indirizzo email dello sviluppatore dopo l'esecuzione della verifica della chiave API.

A queste variabili viene anteposto il prefisso:

verifyapikey.{policy_name}

In questo esempio, il nome del criterio Verifica chiave API è "verify-api-key". Pertanto, fai riferimento al nome di battesimo dello sviluppatore che effettua la richiesta accedendo alla variabile verifyapikey.verify-api-key.developer.firstName.

Imparare ad utilizzare Apigee

Informazioni sulle norme relative alla verifica della chiave API

Quando uno sviluppatore registra un'app su Apigee, Apigee genera automaticamente una coppia di chiave consumer e segreto. Puoi visualizzare la coppia di chiave consumer e segreto dell'app nell'interfaccia utente di Apigee o accedervi dall'API Apigee.

Al momento della registrazione dell'app, lo sviluppatore seleziona uno o più prodotti API da associare all'app, dove un prodotto API è una raccolta di risorse accessibili tramite i proxy API. Lo sviluppatore poi passa la chiave API (chiave consumer) 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 saperne di più, visita la home page di OAuth.

Apigee compila automaticamente un insieme di variabili di flusso durante l'esecuzione del criterio Verifica chiave API. Per saperne di più, consulta la sezione Variabili di flusso di seguito.

Riferimento elemento

Di seguito sono riportati gli elementi e gli attributi che puoi configurare in 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"/>
    <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/>
</VerifyAPIKey>

Attributi <VerifyAPIKey>

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

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

La tabella seguente descrive gli attributi comuni a tutti gli elementi principali dei criteri:

Attributo Descrizione Predefinito Presenza
name

Il nome interno del criterio. Il valore dell'attributo name può contenere lettere, numeri, spazi, trattini, trattini bassi e punti. Questo valore non può superare i 255 caratteri.

Se vuoi, utilizza l'elemento <DisplayName> per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta su false per restituire un errore quando un criterio non va a buon fine. Questo è un comportamento previsto per la maggior parte dei criteri.

Imposta su true per continuare l'esecuzione del flusso anche dopo un fallimento del criterio. Vedi anche:

 falso Facoltativo
enabled

Imposta su true per applicare il criterio.

Imposta false per disattivare il criterio. Il criterio non verrà applicato anche se rimane collegato a un flusso.

 true Facoltativo
async

Questo attributo è stato ritirato.

 falso Ritirato

Elemento <DisplayName>

Da utilizzare insieme all'attributo name per etichettare il criterio nell'editor proxy dell'interfaccia utente di gestione con un nome diverso in linguaggio naturale.

<DisplayName>Policy Display Name</DisplayName>
Predefinito

N/D

Se ometti questo elemento, viene utilizzato il valore dell'attributo name del criterio.
Presenza Facoltativo
Tipo Stringa

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 query, in un'intestazione HTTP o in un parametro di un modulo. Ad esempio, se la chiave viene inviata in un intestazione denominata x-apikey, la chiave verrà trovata nella variabile: request.header.x-apikey

Predefinito NA
Presenza Obbligatorio
Tipo Stringa

Attributi

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

Attributo Descrizione Predefinito Presenza
ref

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

 N/D Obbligatorio

Esempi

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

Come parametro di query:

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

Elemento <CacheExpiryInSeconds>

Questo elemento applica il TTL alla cache, il che consente di personalizzare il periodo di tempo per la scadenza del token di accesso memorizzato nella cache. L'intervallo supportato è compreso tra 1 e 180 secondi. Puoi fornire una variabile di flusso e una variabile predefinita. Se specificato, il valore della variabile di flusso ha la precedenza sul valore predefinito specificato. 

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

Se ometti questo elemento, il periodo di scadenza predefinito per il token di accesso memorizzato nella cache è di 180 secondi.
Presenza Facoltativo
Tipo Numero intero
Valori validi Qualsiasi numero intero positivo diverso da zero. Specifica la data e l'ora di scadenza in secondi.

Attributi

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

Attributo Descrizione Predefinito Presenza
ref

Un riferimento alla variabile di flusso contenente il valore per la scadenza della cache, espresso in secondi.

Se specificato, il valore della variabile di flusso ha la precedenza sul valore predefinito specificato.

 N/D Facoltativo

Schemi

Variabili di flusso

Quando un criterio Verifica chiave API viene applicato a una chiave API valida, Apigee 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
  • Analisi
  • Monetizzazione

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 tabella seguente elenca le variabili di flusso generali compilate dal criterio Verifica chiave API. A queste variabili viene anteposto il prefisso:

verifyapikey.{policy_name}

Ad esempio: verifyapikey.{policy_name}.client_id

Le variabili disponibili includono:

Variabile Descrizione
client_id La chiave utente (chiave API o chiave dell'app) fornita dall'app che effettua la richiesta.
client_secret Il secret consumer associato alla chiave consumer.
redirection_uris Eventuali URI di reindirizzamento nella richiesta.
developer.app.id

L'ID dello sviluppatore o dell'app AppGroup che effettua la richiesta.
developer.app.name Il nome dell'app dello sviluppatore o dell'app AppGroup che effettua la richiesta.
developer.id

L'ID dello sviluppatore o del AppGroup registrato come proprietario dell'app che richiede l'accesso.
developer.{custom_attrib_name} Eventuali attributi personalizzati derivati dal profilo della chiave dell'app.
DisplayName Il valore dell'attributo <DisplayName> del criterio.
failed Impostato 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 dell'API.
apiproduct.developer.quota.limit* L'eventuale limite di quota impostato sul prodotto API.
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 su come configurare i prodotti API, consulta Gestire i prodotti API.

Variabili di flusso di app

Le seguenti variabili di flusso contenenti informazioni sull'app vengono compilate dal criterio. A queste variabili viene anteposto il prefisso:

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 "attivo" o "non attivo"
appType Il tipo di app come "Sviluppatore".
appParentId L'ID dell'app principale.
created_at La data/l'ora in cui è stata creata l'app.
created_by L'indirizzo email dello sviluppatore che ha creato l'app.
last_modified_at La data/l'ora dell'ultimo aggiornamento dell'app.
last_modified_by L'indirizzo email dello sviluppatore che ha aggiornato per ultimo l'app.
{app_custom_attributes} Qualsiasi attributo dell'app personalizzato. Specifica il nome dell'attributo personalizzato.

Variabili di flusso di AppGroup

Le seguenti variabili di flusso contenenti informazioni sugli AppGroups vengono compilate dal criterio. Questi attributi AppGroup vengono compilati solo se verifyapikey.{policy_name}.app.appType è "AppGroup".

A queste variabili viene anteposto il prefisso:

verifyapikey.{policy_name}.appgroup.

Ad esempio:

verifyapikey.{policy_name}.appgroup.name

Le variabili disponibili includono:

Variabile Descrizione
name Il nome di AppGroup.
id L'ID gruppo di app.
displayName Il nome visualizzato di AppGroup.
appOwnerStatus Lo stato del proprietario dell'app: "active", "inactive" o "login_lock".
created_at Il timestamp della data/dell'ora di creazione del gruppo di app.
created_by L'indirizzo email dello sviluppatore che ha creato il gruppo di app.
last_modified_at Il timestamp della data/dell'ora dell'ultima modifica di AppGroup.
last_modified_by L'indirizzo email dello sviluppatore che ha modificato per ultimo il gruppo di app.
{appgroup_custom_attributes} Qualsiasi attributo AppGroup personalizzato. Specifica il nome dell'attributo personalizzato.

Variabili di flusso per gli sviluppatori

Le seguenti variabili di flusso contenenti informazioni sullo sviluppatore vengono compilate dalle norme. A queste variabili viene anteposto il prefisso:

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 La data/l'ora in cui lo sviluppatore è stato creato.
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.

Variabili di Analytics

Le seguenti variabili vengono completate automaticamente in Analytics quando viene applicato un criterio di verifica della chiave API per una chiave API valida. Queste variabili vengono compilate solo dalle norme relative alla verifica della chiave API e dalle norme OAuth.

Le variabili e i valori possono essere utilizzati come dimensioni per creare report di Analytics al fine di ottenere una maggiore visibilità sui pattern di consumo da parte di sviluppatori e app.

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

Variabili di flusso di monetizzazione

Dopo aver autenticato l'utente, il criterio VerifyAPIKey controlla tutti i piani tariffari pubblicati per determinare se sono attivi in base ai relativi tempi di attivazione e scadenza. Se viene trovato un piano tariffario pubblicato attivo, vengono compilate le seguenti variabili di flusso:

Variabile Descrizione
mint.mintng_is_apiproduct_monetized true se viene trovato un piano tariffario pubblicato attivo.
mint.mintng_rate_plan_id ID piano tariffario.
mint.rateplan_end_time_ms Data e ora di scadenza del piano tariffario. Ad esempio: 1619433556408
mint.rateplan_start_time_ms Ora di attivazione del piano tariffario. Ad esempio: 1618433956209

Messaggi di errore

Questa sezione descrive i codici di errore e i messaggi di errore restituiti e le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti se stai sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta Informazioni importanti sugli errori relativi alle norme e Gestione degli errori.

Errori di runtime

Questi errori possono verificarsi durante l'esecuzione del criterio.

Codice guasto Stato HTTP Causa
keymanagement.service.consumer_key_missing_api_product_association 400

Nella credenziale dell'applicazione manca un'associazione del prodotto API. Associa l'applicazione della chiave a un prodotto API. Tieni presente che questo vale per tutti i tipi di applicazioni, come le app per sviluppatori e le app di AppGroup.
keymanagement.service.DeveloperStatusNotActive 401

Lo sviluppatore che ha creato l'app per sviluppatori con la chiave API che stai utilizzando ha uno stato inattivo. Quando lo stato di uno sviluppatore di app è impostato su inattivo, tutte le app sviluppatore create dallo sviluppatore vengono disattivate. Un utente amministratore con le autorizzazioni appropriate (ad esempio Amministratore dell'organizzazione) può modificare lo stato di uno sviluppatore nei modi seguenti:
keymanagement.service.invalid_client-app_not_approved 401 L'app per sviluppatori associata alla chiave API è revocata. Un'app revocata non può accedere a nessun prodotto API e non può invocare alcuna API gestita da Apigee. Un amministratore dell'organizzazione può modificare lo stato di un'app per sviluppatori utilizzando l'API Apigee. Consulta Generare una coppia di chiavi o aggiornare lo stato dell'app sviluppatore.
oauth.v2.FailedToResolveAPIKey 401 Il criterio si aspetta di trovare la chiave API in una variabile specificata nell'elemento <APIKey> del criterio. Questo errore si verifica quando la variabile prevista non esiste (non può essere risolta).
oauth.v2.InvalidApiKey 401 Apigee ha ricevuto una chiave API, ma non è valida. Quando Apigee cerca la chiave nel suo database, deve corrispondere esattamente a quella inviata nella richiesta. Se l'API funzionava in precedenza, assicurati che la chiave non sia stata rigenerata. Se la chiave è stata rigenerata, vedrai questo errore se provi a utilizzare la vecchia chiave. Per maggiori dettagli, consulta Controllo dell'accesso alle API mediante la registrazione delle app.
oauth.v2.InvalidApiKeyForGivenResource 401 Apigee ha ricevuto una chiave API valida, ma non corrisponde a una chiave approvata nell'app per sviluppatori associata al tuo proxy API tramite un prodotto.

Errori di deployment

Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.

Nome dell'errore Causa
SpecifyValueOrRefApiKey Per l'elemento <APIKey> non è stato specificato un valore o una chiave.

Variabili di errore

Queste variabili vengono impostate quando si verifica un errore di runtime. Per ulteriori informazioni, consulta Informazioni importanti sugli errori relativi alle norme.

Variabili Dove Esempio
fault.name="fault_name" fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime sopra. Il nome dell'errore è l'ultima parte del codice dell'errore. fault.name Matches "FailedToResolveAPIKey"
oauthV2.policy_name.failed policy_name è il nome specificato dall'utente del criterio che ha generato l'errore. oauthV2.VK-VerifyAPIKey.failed = true

Risposte di errore di esempio

{  
   "fault":{  
      "faultstring":"Invalid ApiKey",
      "detail":{  
         "errorcode":"oauth.v2.InvalidApiKey"
      }
   }
}
 
{  
   "fault":{  
      "detail":{  
         "errorcode":"keymanagement.service.DeveloperStatusNotActive"
      },
      "faultstring":"Developer Status is not Active"
   }
}

Esempio di regola di errore

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