Questa pagina si applica ad Apigee e Apigee hybrid.
Visualizza la documentazione di Apigee Edge.
Panoramica
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, che non siano state revocate e che siano approvate per l'utilizzo delle risorse specifiche associate ai tuoi prodotti API.
Questo criterio è un criterio estendibile e il suo utilizzo potrebbe avere implicazioni in termini di costi o utilizzo, a seconda della licenza Apigee. Per informazioni sui tipi di criteri e sulle implicazioni di 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 chiavi API.
Esempi
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 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
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 Apigee 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 dipende da 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>
Apigee 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, ID app e informazioni sullo sviluppatore o sull'azienda che ha registrato l'app. Nell'esempio precedente, utilizzi il criterio Assegna messaggi 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 della chiave API di verifica è "verify-api-key". Devi quindi fare riferimento al nome dello sviluppatore che effettua la richiesta accedendo alla variabile verifyapikey.verify-api-key.developer.firstName.
Scopri Apigee
Informazioni sul criterio Verifica chiave API
Quando uno sviluppatore registra un'app su Apigee, Apigee genera automaticamente una coppia chiave e secret consumer. Puoi visualizzare la coppia chiave e secret utente 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. Un prodotto API è una raccolta di risorse accessibili tramite proxy API. Quindi, lo sviluppatore passa la chiave API (chiave utente) come parte di ogni richiesta a un'API in un prodotto API associato all'app. Per ulteriori informazioni, 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 OAuth a casa.
Apigee compila automaticamente un insieme di variabili di flusso durante l'esecuzione del criterio di verifica della 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 per 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>
Il seguente esempio mostra gli attributi nel 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 della norma. Il valore dell'attributo Facoltativamente, utilizza l'elemento |
N/A | Obbligatorio |
continueOnError |
Impostalo su Imposta su |
false | Facoltativo |
enabled |
Imposta il criterio su Impostala su |
true | Facoltativo |
async |
Questo attributo è obsoleto. |
false | Deprecata |
Elemento <DisplayName>
Utilizzalo in aggiunta 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/A Se ometti questo elemento, viene utilizzato il valore dell'attributo |
---|---|
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 modulo. Ad esempio, se la chiave viene inviata in un'intestazione
denominata x-apikey
, la chiave si troverà 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 |
---|---|---|---|
rif |
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 di modulo HTTP:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
Elemento <CacheExpiryInSecond>
Questo elemento applica il valore TTL sulla cache, che consente la personalizzazione del 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 predefinita. Se fornito, 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 è 180 secondi. |
---|---|
Presenza | Facoltativo |
Tipo | Numero intero |
Valori validi | Qualsiasi numero intero positivo diverso da zero. Specifica la scadenza in secondi. |
Attributi
La tabella seguente descrive gli attributi dell'elemento <CacheExpiryInSeconds>
Attributo | Descrizione | Predefinito | Presenza |
---|---|---|---|
rif |
Un riferimento alla variabile di flusso contenente il valore per la scadenza della cache, espressa in secondi. Se fornito, il valore della variabile di flusso ha la precedenza sul valore predefinito specificato. |
N/D | Facoltativo |
Schema
Variabili di flusso
Quando un criterio di verifica della chiave API viene applicato su una chiave API valida, Apigee completa un set di variabili di flusso. Queste variabili sono disponibili per i criteri o il codice eseguito in un secondo momento nel flusso e sono spesso utilizzate per eseguire elaborazioni personalizzate 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:
- Generico
- 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
Nella tabella seguente sono elencate 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 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 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 per l'eventuale prodotto API. |
apiproduct.developer.quota.timeunit* |
L'unità di tempo della quota impostata sul prodotto API, se presente. |
* Le variabili di prodotto 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
Gestione dei prodotti API. |
Variabili di flusso 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'elemento padre dell'app, ad esempio "attivo" o "inattivo" |
appType |
Il tipo di app "Sviluppatore". |
appParentId |
L'ID dell'app principale. |
created_at |
Il timestamp 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 dell'ultimo aggiornamento dell'app. |
{app_custom_attributes} |
Qualsiasi attributo personalizzato dell'app. Specifica il nome dell'attributo personalizzato. |
Variabili di flusso AppGroup
Le seguenti variabili di flusso contenenti informazioni su
AppGroups
vengono compilate dal criterio. Questi attributi di AppGroup vengono compilati solo se
verifyapikey.{policy_name}.app.appType
è "AppGroup".
Queste variabili sono tutte precedute da:
verifyapikey.{policy_name}.appgroup
.
Ad esempio:
verifyapikey.{policy_name}.appgroup.name
Le variabili disponibili includono:
Variabile | Descrizione |
---|---|
name |
Il nome del gruppo di app. |
id |
L'ID AppGroup. |
displayName |
Il nome visualizzato del gruppo di app. |
appOwnerStatus |
Lo stato del proprietario dell'app: "attivo", "inattivo" o "login_lock". |
created_at |
Il timestamp di data e ora della creazione del gruppo di app. |
created_by |
L'indirizzo email dello sviluppatore che ha creato il gruppo di app. |
last_modified_at |
Il timestamp dell'ultima modifica del gruppo di app. |
last_modified_by |
L'indirizzo email dello sviluppatore che ha modificato il gruppo di app per ultimo. |
{appgroup_custom_attributes} |
Qualsiasi attributo AppGroup personalizzato. Specifica il nome dell'attributo personalizzato. |
Variabili di flusso sviluppatore
Le seguenti variabili di flusso contenenti informazioni sullo sviluppatore vengono compilate 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 |
Cognome dello sviluppatore. |
email |
L'indirizzo email dello sviluppatore. |
status |
Lo stato dello sviluppatore, ovvero attivo, non attivo o login_lock. |
apps |
Un array di app associate allo sviluppatore. |
created_at |
Il timestamp 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. |
Variabili di Analytics
Le seguenti variabili vengono compilate automaticamente in Analytics quando viene applicato in modo forzato un criterio di verifica della chiave API per una chiave API valida. Queste variabili vengono compilate solo dal criterio di verifica della 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
Variabili del flusso di monetizzazione
Dopo l'autenticazione dell'utente, il criterio VerificationAPIKey controlla tutti i piani tariffari pubblicati per determinare se sono attivi in base alla relativa attivazione e alla scadenza. Se viene trovato un piano tariffario 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 |
Scadenza del piano tariffario. Ad esempio: 1619433556408 |
mint.rateplan_start_time_ms |
Ora di attivazione del piano tariffario. Ad esempio: 1618433956209 |
Messaggi di errore
In questa sezione vengono descritti i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Apigee quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se stai sviluppando regole di errore per gestirle. Per scoprire di più, consulta Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi durante l'esecuzione del criterio.
Codice di errore | Stato HTTP | Causa |
---|---|---|
keymanagement.service.consumer_key_missing_api_product_association |
400 |
Alla credenziale dell'applicazione manca un'associazione di prodotto API. Associa l'applicazione della chiave a un prodotto API. Tieni presente che questo vale per tutti i tipi di applicazioni, ad esempio le app per sviluppatori e le app AppGroup. |
keymanagement.service.DeveloperStatusNotActive |
401 |
Lo stato non attivo dello sviluppatore che ha creato l'app sviluppatore con la chiave API che stai utilizzando. Quando lo stato di uno sviluppatore di app è impostato su inattivo, tutte le app sviluppatore create da tale sviluppatore vengono disattivate. Un utente amministratore con le autorizzazioni appropriate (ad esempio Amministratore dell'organizzazione) può modificare lo stato di uno sviluppatore nei seguenti modi:
|
keymanagement.service.invalid_client-app_not_approved |
401 |
L'app sviluppatore associata alla chiave API è stata revocata. Un'app revocata non può accedere a nessun prodotto API e non può richiamare un'API gestita da Apigee. Un amministratore dell'organizzazione può modificare lo stato di un'app sviluppatore utilizzando l'API Apigee. Consulta la pagina Generare una coppia di chiavi o Aggiornare lo stato dell'app sviluppatore. |
oauth.v2.FailedToResolveAPIKey |
401 |
Il criterio prevede 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 |
Una chiave API è stata ricevuta da Apigee, 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, riceverai questo errore se tenti di utilizzare la chiave precedente. Per maggiori dettagli, consulta Controllare l'accesso alle API registrando le app. |
oauth.v2.InvalidApiKeyForGivenResource |
401 |
Una chiave API è stata ricevuta da Apigee ed è valida; tuttavia, non corrisponde a una chiave approvata nell'app per sviluppatori associata al proxy API tramite un prodotto. |
Errori di deployment
Questi errori possono verificarsi quando esegui il deployment di un proxy contenente questo criterio.
Nome 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 maggiori informazioni, consulta l'articolo Cosa devi sapere sugli errori dei criteri.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, 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 |
Esempi di risposte di errore
{ "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>