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">
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 | Obbligatorie |
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 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
Questa sezione descrive i codici e i messaggi di errore restituiti e le variabili di errore impostate da Edge quando questo criterio attiva un errore. Queste informazioni sono importanti per sapere se si stanno sviluppando regole di errore per gestire gli errori. Per scoprire di più, consulta gli articoli Cosa devi sapere sugli errori relativi alle norme e Gestione degli errori.
Errori di runtime
Questi errori possono verificarsi quando il criterio viene eseguito.
| Codice di errore | Stato HTTP | Causa |
|---|---|---|
keymanagement.service.CompanyStatusNotActive |
401 | La società associata all'app sviluppatore con la chiave API che stai utilizzando è in stato non attivo. Quando lo stato di una società è impostato su inattivo, non puoi accedere agli sviluppatori o alle app associati a tale società. Un amministratore dell'organizzazione può modificare lo stato di una società utilizzando l'API di gestione. Consulta Impostare lo stato di un'azienda. |
keymanagement.service.DeveloperStatusNotActive |
401 |
Lo stato dello sviluppatore che ha creato l'app con la chiave API che stai utilizzando è inattivo. Quando lo stato di uno sviluppatore di app è impostato su inattivo, tutte le app per sviluppatori 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 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 alcuna API gestita da Apigee Edge. Un amministratore dell'organizzazione può modificare lo stato di un'app sviluppatore utilizzando l'API di gestione. Vedi Approvare o revocare l'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 Edge, ma non è valida. Quando Edge cerca la chiave nel proprio 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 chiave precedente. Per maggiori dettagli, consulta Registrare app e gestire le chiavi API. |
oauth.v2.InvalidApiKeyForGivenResource |
401 | Una chiave API è stata ricevuta da Edge 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 la sezione Cosa devi sapere sugli errori relativi ai criteri.
| Variabili | Dove | Esempio |
|---|---|---|
fault.name="fault_name" |
fault_name è il nome dell'errore, come indicato nella tabella Errori di runtime riportata sopra. Il nome del guasto è l'ultima parte del codice di 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>