Questa pagina si applica a Apigee e Apigee ibridi.
Visualizza la documentazione di Apigee Edge.
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 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"
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 usare queste variabili per accedere a informazioni quali l'app nome, ID app e informazioni sullo sviluppatore o sull'azienda che ha registrato l'app. Nella Nell'esempio precedente, utilizzi il criterio Assegna messaggio per accedere al nome e al cognome dello sviluppatore nome e indirizzo email dopo l'esecuzione della chiave API Verify.
Queste variabili hanno tutte un prefisso:
verifyapikey.{policy_name}
In questo esempio, il nome del criterio di verifica della chiave API è "verify-api-key". Pertanto, fai riferimento
il nome dello sviluppatore che ha effettuato la richiesta accedendo al
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 chiave consumer e una coppia segreta. Puoi visualizzare la chiave utente e la coppia secret dell'app nella UI di Apigee o accedervi dell'API Apigee.
Al momento della registrazione dell'app, lo sviluppatore seleziona uno o più prodotti API per Associare all'app, dove un prodotto API è una raccolta di risorse accessibili tramite proxy API. Lo sviluppatore passa quindi la chiave API (chiave utente) come parte del ogni richiesta a un'API in un prodotto API associato all'app. Per saperne di più, consulta 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ù, consulta Home page di OAuth.
Apigee compila automaticamente un insieme di variabili di flusso durante l'esecuzione del criterio della chiave API Verify. Vedi Flusso variabili 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"/> <CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Default value</CacheExpiryInSeconds/> </VerifyAPIKey>
<VerifyAPIKey> attributi
L'esempio seguente 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 del criterio. Il valore dell'attributo Se vuoi, utilizza l'elemento |
N/D | Obbligatorio |
continueOnError |
Imposta il valore su Imposta su |
falso | Facoltativo |
enabled |
Imposta su Imposta |
true | Facoltativo |
async |
Questo attributo è stato ritirato. |
falso | Ritirato |
<DisplayName> elemento
Da utilizzare in aggiunta all'attributo name
per etichettare il criterio in
editor proxy della UI di gestione con un nome diverso e in linguaggio naturale.
<DisplayName>Policy Display Name</DisplayName>
Predefinito |
N/D Se ometti questo elemento, il valore dell'attributo |
---|---|
Presenza | Facoltativo |
Tipo | Stringa |
<APIKey> elemento
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 |
---|---|---|---|
riferimento |
Un riferimento alla variabile che contiene la chiave API. È consentita una sola località in base al 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 HTTP del modulo:
<VerifyAPIKey name="APIKeyVerifier"> <APIKey ref="request.formparam.x-apikey"/> </VerifyAPIKey>
<CacheExpiryInSeconds> elemento
Questo elemento applica il TTL sulla cache, il 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 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 per il codice eseguito più avanti nel flusso e sono spesso utilizzati per eseguire elaborazioni personalizzate in base ad 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
- Analytics
- Monetizzazione
Ogni tipo di variabile di flusso ha un prefisso diverso. Tutte le variabili sono scalari ad eccezione di quelle indicate specificatamente come array.
Variabili di flusso generali
La tabella seguente elenca le variabili di flusso generali compilate dal criterio Verifica chiave API. Queste variabili hanno tutte un 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 AppGroup che effettua la richiesta. |
developer.app.name |
Il nome dell'app dello sviluppatore o AppGroup che effettua la richiesta. |
developer.id |
L'ID dello sviluppatore o AppGroup registrato come proprietario dell'app richiedente. |
developer.{custom_attrib_name} |
Tutti gli attributi personalizzati derivati dal profilo della chiave dell'app. |
DisplayName |
Il valore del parametro <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'istanza . |
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 quota impostato per il prodotto API. |
apiproduct.developer.quota.interval* |
L'intervallo di quota impostato sul prodotto API, se presente. |
apiproduct.developer.quota.timeunit* |
L'unità di tempo quota impostata per il 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 (derivanti da
proxy.pathsuffix ). Per istruzioni sulla configurazione di prodotti basati su API, consulta
Gestione dei prodotti API. |
Variabili di flusso dell'app
Il criterio compila le seguenti variabili di flusso contenenti informazioni sull'app. 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 "Ritirata". |
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'account principale dell'app, 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 l'app per ultimo. |
{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".
Queste variabili hanno tutte un prefisso:
verifyapikey.{policy_name}.appgroup
.
Ad esempio:
verifyapikey.{policy_name}.appgroup.name
Le variabili disponibili includono:
Variabile | Descrizione |
---|---|
name |
Il nome dell'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 l'AppGroup. |
last_modified_at |
La data e l'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 sviluppatori
Le seguenti variabili di flusso contenenti informazioni sullo sviluppatore vengono compilate dalla . 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 |
Data e ora di creazione dello sviluppatore. |
created_by |
L'indirizzo email dell'utente che ha creato lo sviluppatore. |
last_modified_at |
Il timestamp della data/dell'ora 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 e ottenere visibilità sui modelli 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 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 e i messaggi di errore restituiti, nonché 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 saperne di più, consulta Cosa devi sapere sugli errori relativi ai criteri e sulla gestione di errore.
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 |
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 tutte le richieste di ad esempio le app per sviluppatori e le app 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 es. Amministratore organizzazione) può modificare lo stato di uno sviluppatore nei seguenti modi: modi:
|
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: Genera una coppia di chiavi o aggiorna 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 il valore previsto 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 usare la chiave precedente. Per maggiori dettagli, vedi Controllo dell'accesso alle API tramite la registrazione delle app. |
oauth.v2.InvalidApiKeyForGivenResource |
401 |
Una chiave API è stata ricevuta da Apigee ed è valida; ma non corrisponde chiave approvata nell'App sviluppatore 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 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, vedi Cosa devi sapere sugli errori relativi alle norme.
Variabili | Dove | Esempio |
---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come elencato nella precedente tabella Errori di runtime. 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>