Criterio VerifyAPIKey

Stai visualizzando la documentazione di Apigee Edge.
Vai alla sezione Documentazione di Apigee X. Informazioni

Cosa

Il criterio Verifica chiave API consente di applicare la verifica delle chiavi API in fase di runtime, consentendo le app con chiavi API approvate accedono alle API. Questo criterio garantisce che le chiavi API siano valide, abbiano non sono stati revocati e vengono approvati per utilizzare le risorse specifiche associate all'API prodotti di big data e machine learning.

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

Sei tu a decidere come compilare la variabile. Ad esempio, puoi utilizzare il comando Estrai Criterio delle variabili per compilare requestAPIKey.key da un parametro di query denominata myKey, come mostrato sotto:

<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 della chiave API Verify 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 Ad esempio riportato sopra, 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.

Impara a usare Edge

Informazioni sul criterio di verifica della chiave API

Quando uno sviluppatore registra un'app su Edge, Edge genera automaticamente una chiave utente e una coppia segreta. Puoi visualizzare la coppia chiave utente e segreto dell'app nella UI di Edge o accedervi dell'API Edge.

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 l'accesso OAuth di token. 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.

Edge compila automaticamente un insieme di variabili di flusso durante l'esecuzione del criterio Verify API Key. 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"/>
</VerifyAPIKey>

&lt;VerifyAPIKey&gt; 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 del criterio:

Attributo Descrizione Predefinito Presenza
name

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

Se vuoi, puoi utilizzare l'elemento <DisplayName> per etichettare il criterio in l'editor proxy della UI di gestione con un nome diverso in linguaggio naturale.

 N/D Obbligatorio
continueOnError

Imposta il valore su false per restituire un errore quando un criterio non viene eseguito. Si tratta di un comportamento previsto per la maggior parte dei criteri.

Imposta su true per fare in modo che l'esecuzione del flusso continui anche dopo un criterio non riesce.

 falso Facoltativo
enabled

Imposta il valore su true per applicare il criterio.

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

 true Facoltativo
async

Questo attributo è obsoleto.

 falso Deprecato

&lt;DisplayName&gt; 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 name del criterio è in uso.
Presenza Facoltativo
Tipo Stringa

&lt;APIKey&gt; elemento

Questo elemento specifica la variabile di flusso che contiene la chiave API. Di solito, il client invia la chiave API in un parametro di query, in un'intestazione HTTP o in un parametro del modulo. Ad esempio, se la chiave viene inviata in un'intestazione denominata x-apikey, la chiave si trova nella variabile: request.header.x-apikey

Predefinito ND
Presenza Obbligatorio
Tipo Stringa

Attributi

Nella tabella seguente vengono descritti 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>

Schemi

Variabili di flusso

Quando un criterio di verifica della chiave API viene applicato a una chiave API valida, Edge compila un set di flussi come la codifica one-hot delle variabili categoriche. 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
  • Società
  • Analytics

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 seguente tabella elenca le variabili di flusso generali compilate dal criterio Verify API Key. 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 (ovvero chiave API o chiave dell'app) fornita dall'app richiedente.
client_secret Il segreto utente associato alla chiave utente.
redirection_uris Eventuali URI di reindirizzamento nella richiesta.
developer.app.id

L'ID dell'app 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} 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 ha esito negativo.
{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 API.
apiproduct.developer.quota.limit* L'eventuale limite quota impostato per il prodotto API.
apiproduct.developer.quota.interval* L'intervallo di quota impostato nel 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 Utilizzo di Edge per la pubblicazione delle API.

Variabili di flusso delle app

Il criterio compila le seguenti variabili di flusso contenenti informazioni sull'app. Queste variabili hanno tutte un 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 "revocato".
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 "Azienda" o "Sviluppatore".
appParentId L'ID dell'app principale.
created_at Data e ora di creazione dell'app.
created_by L'indirizzo email dello sviluppatore che ha creato l'app.
last_modified_at La data e l'ora dell'ultimo aggiornamento dell'app.
last_modified_by L'indirizzo email dello sviluppatore che ha aggiornato l'ultima volta l'app.
{app_custom_attributes} Qualsiasi attributo dell'app personalizzato. Specifica il nome dell'attributo personalizzato.

Variabili di flusso per sviluppatori

Le seguenti variabili di flusso contenenti informazioni sullo sviluppatore vengono compilate dalla . Queste variabili hanno tutte un 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 e l'ora di creazione dello sviluppatore.
created_by L'indirizzo email dell'utente che ha creato lo sviluppatore.
last_modified_at La data e l'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.
Company Il nome dell'azienda, se presente, associata allo sviluppatore.

Variabili di flusso aziendali

Le seguenti variabili di flusso contenenti informazioni sull'azienda vengono compilate dalla . Queste variabili hanno tutte un prefisso:

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 azienda.
apps Un array contenente l'elenco delle app aziendali.
appOwnerStatus
Lo stato del proprietario dell'app, ad esempio attivo, non attivo o login_lock.
created_at Data e ora di creazione dell'azienda.
created_by L'indirizzo email dell'utente che ha creato l'azienda.
last_modified_at Data e ora dell'ultima modifica dell'azienda.
last_modified_by L'indirizzo email dell'utente che ha modificato l'azienda per l'ultima volta.
{company_custom_attributes} Qualsiasi attributo personalizzato dell'azienda. Specifica il nome dell'attributo personalizzato.

Variabili di Analytics

Le seguenti variabili vengono compilate automaticamente in Analytics quando una norma Verifica della chiave API viene applicata in modo forzato a una chiave API valida. Queste variabili vengono compilate solo dalla chiave Verify API e i criteri 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

Messaggi di errore

Questa sezione descrive i codici e i messaggi di errore restituiti, nonché le variabili di errore impostate da Edge quando questo criterio attiva un errore. È importante sapere se stai sviluppando regole di errore per 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 quando il criterio viene eseguito.

Codice di errore Stato HTTP Causa
keymanagement.service.CompanyStatusNotActive 401 La società associata all'app sviluppatore che dispone della chiave API in uso ha un non attivo. Quando lo stato di un'azienda è impostato su inattivo, non puoi accedere ai sviluppatori o app associati all'Azienda. Un amministratore dell'organizzazione può modificare lo stato di un'azienda utilizzando l'API di gestione. Consulta l'articolo Impostare lo stato. di una Società.
keymanagement.service.DeveloperStatusNotActive 401

Lo sviluppatore che ha creato l'app sviluppatore con la chiave API che stai utilizzando ha non attivo. Quando lo stato di uno sviluppatore di app è impostato su Inattivo, qualsiasi app sviluppatore create dallo sviluppatore vengono disattivate. Un utente amministratore con le autorizzazioni appropriate (ad es. Amministratore dell'organizzazione) può modificare lo stato di uno sviluppatore nei seguenti modi: modi:
keymanagement.service.invalid_client-app_not_approved 401 L'app sviluppatore associata alla chiave API è stata revocata. Un'app revocata non può accede a qualsiasi 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 nella relativa &lt;APIKey&gt; . Questo errore si verifica quando il valore previsto 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 deve corrispondere esattamente a quello inviato nella richiesta. Se l'API ha funzionato 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 Registrare app e gestire l'API chiave.
oauth.v2.InvalidApiKeyForGivenResource 401 Una chiave API è stata ricevuta da Edge 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 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>

Argomenti correlati