Riferimento per le operazioni e la configurazione di Edge Microgateway

Messaggi di errore

Alcune voci di log conterranno messaggi di errore. Per identificare dove e perché si verificano gli errori, consulta la documentazione di riferimento sugli errori Microgateway Edge.

Riferimento per la configurazione di Edge Microgateway

Percorso del file di configurazione

Gli attributi di configurazione descritti in questa sezione si trovano nel file di configurazione di Edge Microgateway. Vedi anche Apportare modifiche alla configurazione.

Attributi edge_config

Queste impostazioni vengono utilizzate per configurare l'interazione tra l'istanza Edge Microgateway e Apigee Edge.

• bootstrap: (predefinito: nessuno) un URL che rimanda a un servizio specifico del Microgateway Edge in esecuzione su Apigee Edge. Edge Microgateway utilizza questo servizio per comunicare con Apigee Edge. Questo URL viene restituito quando esegui il comando per generare la coppia di chiavi pubblica/privata: edgemicro genkeys. Per maggiori dettagli, consulta Configurazione e configurazione di Edge Microgateway.
• jwt_public_key: (predefinito: nessuno) un URL che rimanda al proxy Edge Microgateway di cui è stato eseguito il deployment su Apigee Edge. Questo proxy funge da endpoint di autenticazione per l'emissione di token di accesso firmati ai client. Questo URL viene restituito quando esegui il comando per eseguire il deployment del proxy: edgemicro configure. Per maggiori dettagli, consulta Configurazione e configurazione di Edge Microgateway.
• quotaUri: imposta questa proprietà di configurazione se vuoi gestire le quote tramite il proxy edgemicro-auth di cui viene eseguito il deployment nella tua organizzazione. Se questa proprietà non è impostata, l'endpoint di quota verrà impostato automaticamente sull'endpoint interno Edge Microgateway.

  edge_config:
    quotaUri: https://your_org-your_env.apigee.net/edgemicro-auth
  

Attributi edgemicro

Queste impostazioni configurano il processo Edge Microgateway.

• port: (predefinito: 8000) il numero di porta su cui il processo Edge Microgateway è in ascolto.
• max_connections: (predefinito: -1) specifica il numero massimo di connessioni in entrata simultanee che Edge Microgateway può ricevere. Se questo numero viene superato, viene restituito il seguente stato:
  
  res.statusCode = 429; // Too many requests
  
• max_connections_hard: (predefinito: -1) il numero massimo di richieste simultanee che Edge Microgateway può ricevere prima di arrestare la connessione. Questa impostazione ha lo scopo di impedire gli attacchi denial of service. In genere, impostalo su un numero maggiore di max_connections.
• :
  • level: (predefinito: errore)
    • informazioni: (consigliato) registra tutte le richieste e risposte che passano attraverso un'istanza Edge Microgateway.
    • warn: registra solo i messaggi di avviso.
    • error: registra solo i messaggi di errore.
    • debug: registra i messaggi di debug insieme a informazioni, avvisi e messaggi di errore.
    • trace: registra le informazioni sulla traccia degli errori insieme a informazioni, avvisi e messaggi di errore.
    • none: non crea un file di log.
  • dir: (impostazione predefinita: /var/tmp) la directory in cui vengono archiviati i file di log.
  • stats_log_interval: (valore predefinito: 60): intervallo, in secondi, durante il quale il record delle statistiche viene scritto nel file di log dell'API.
  • rotate_interval: (valore predefinito: 24): intervallo, in ore, durante la rotazione dei file di log.

• plug-in: i plug-in aggiungono funzionalità a Edge Microgateway. Per maggiori dettagli sullo sviluppo di plug-in, consulta l'articolo Sviluppare plug-in personalizzati.

• dir: un percorso relativo dalla directory ./gateway alla directory ./plugins o un percorso assoluto.
• Sequenza: un elenco di moduli plug-in da aggiungere all'istanza Edge Microgateway. I moduli verranno eseguiti nell'ordine specificato qui.

• debug: aggiunge il debug remoto al processo Edge Microgateway.
  • porta: il numero di porta su cui rimanere in ascolto. Ad esempio, imposta il debugger IDE per l'ascolto su questa porta.
  • args: argomenti del processo di debug. Ad esempio: args --nolazy
    
• config_change_poll_interval: (valore predefinito: 600 secondi) Edge Microgateway carica periodicamente una nuova configurazione ed esegue un ricaricamento in caso di modifiche. Il polling rileva tutte le modifiche apportate su Edge (modifiche ai prodotti, ai proxy sensibili al microgateway e così via) e alle modifiche apportate al file di configurazione locale.
  
• disable_config_poll_interval: (impostazione predefinita: false) Imposta su true per disattivare il polling automatico delle modifiche.
• request_timeout: imposta un timeout per le richieste di destinazione. Il timeout è impostato in secondi. Se si verifica un timeout, Edge Microgateway risponde con un codice di stato 504. (Aggiunta v2.4.x)
• keep_alive_timeout: questa proprietà consente di impostare il timeout (in millisecondi) del Microgateway Edge. (Impostazione predefinita: 5 secondi) (Aggiunta v3.0.6)
• headers_timeout: questo attributo limita il tempo (in millisecondi) che il parser HTTP attende per ricevere le intestazioni HTTP complete.

  Ad esempio:

  edgemicro:
    keep_alive_timeout: 6000
    headers_timeout: 12000

  Internamente, il parametro imposta l'attributo Node.js Server.headersTimeout sulle richieste. (Impostazione predefinita: 5 secondi in più rispetto al tempo impostato con edgemicro.keep_alive_timeout. Questa impostazione predefinita impedisce ai bilanciatori del carico o ai proxy di eliminare erroneamente la connessione. (Aggiunta v3.1.1)

• noRuleMatchAction: (stringa) l'azione da intraprendere (consentire o negare l'accesso) se la regola di corrispondenza specificata nel plug-in accesscontrol non viene risolta (senza corrispondenza). Valori validi: ALLOW o DENY Valore predefinito: ALLOW (aggiunto: v3.1.7)
• enableAnalytics: (predefinito: true) imposta l'attributo su false per impedire il caricamento del plug-in di analisi. In questo caso, non verranno effettuate chiamate all'analisi di Apigee Edge. Se impostato su true o quando questo attributo non viene fornito, il plug-in di analisi funzionerà come di consueto. Per i dettagli, consulta gli attributi edgemicro. (Aggiunta v3.1.8).

  Esempio:

  edgemicro
    enableAnalytics=false|true

• on_target_response_abort: questo attributo consente di controllare il comportamento di Edge Microgateway in caso di chiusura prematura della connessione tra il client (Edge Microgateway) e il server di destinazione.

  Valore	Descrizione
  Predefinito	Se on_target_response_abort non è specificato, il comportamento predefinito consiste nel troncare la risposta senza mostrare un errore. Nei file di log viene visualizzato un messaggio di avviso con targetResponse aborted e un codice di risposta 502.
  appendErrorToClientResponseBody	L'errore personalizzato TargetResponseAborted viene restituito al client. Nei file di log viene visualizzato un messaggio di avviso con targetResponse aborted e un codice di risposta 502. Inoltre, l'errore TargetResponseAborted viene registrato con il messaggio Target response ended prematurely.
  abortClientRequest	Edge Microgateway interrompe la richiesta e viene scritto un avviso nei file di log: TargetResponseAborted con il codice di stato della richiesta 502.

Esempio:

edgemicro:
 on_target_response_abort: appendErrorToClientResponseBody | abortClientRequest

attributi header

Queste impostazioni configurano il modo in cui vengono trattate determinate intestazioni HTTP.

• x-forwarded-for: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-forwarded-for alla destinazione. Tieni presente che, se la richiesta contiene un'intestazione x-forwarded-for, il relativo valore verrà impostato sul valore client-ip in Edge Analytics.
• x-forwarded-host: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-forwarded-host alla destinazione.
• x-request-id: (valore predefinito: true) impostalo su false per impedire il trasferimento delle intestazioni x-request-id alla destinazione.
• x-response-time: (valore predefinito: true) impostato su false per impedire il passaggio delle intestazioni x-response-time al target.
• via: (predefinito: true) viene impostato su false per impedire il trasferimento tramite intestazioni alla destinazione.

Attributi OAuth

Queste impostazioni configurano il modo in cui l'autenticazione client viene applicata da Edge Microgateway.

• allowNoAuthorization: (predefinito: false) se viene impostato su true, le chiamate API possono passare attraverso Edge Microgateway senza alcuna intestazione Authorization. Impostalo su false per richiedere un'intestazione di autorizzazione (impostazione predefinita).
• allowInvalidAuthorization: (valore predefinito: false) se impostato su true, le chiamate API possono essere trasmesse se il token trasmesso nell'intestazione Authorization non è valido o è scaduto. Impostalo su false per richiedere token validi (impostazione predefinita).
• permission-header: (predefinito: Authorization: Bearer) l'intestazione utilizzata per inviare il token di accesso a Edge Microgateway. Puoi modificare l'impostazione predefinita nei casi in cui la destinazione debba utilizzare l'intestazione Authorization per altri scopi.
• api-key-header: (predefinito: x-api-key) il nome dell'intestazione o del parametro di query utilizzato per passare una chiave API a Edge Microgateway. Vedi anche Utilizzo di una chiave API.
• keep-permissions-header: (impostazione predefinita: false) se è impostata su true, l'intestazione Authorization inviata nella richiesta viene trasmessa alla destinazione (viene conservata).
• allowOAuthOnly: se è impostato su true, ogni API deve includere un'intestazione Authorization con un token di accesso di connessione. Consente di consentire solo il modello di sicurezza OAuth (mantenendo la compatibilità con le versioni precedenti). (2.4.x aggiunta)
• allowAPIKeyOnly: se è impostata su true, ogni API deve avere un'intestazione x-api-key (o una posizione personalizzata) con una chiave API.Consente di autorizzare solo il modello di sicurezza della chiave API, mantenendo la compatibilità con le versioni precedenti. (Aggiunta 2.4.x)
• gracePeriod: questo parametro consente di evitare errori causati da lievi discrepanze tra l'orologio di sistema e gli orari Non prima (nbf) o Emesso alle (iat) specificati nel token di autorizzazione JWT. Imposta questo parametro sul numero di secondi per consentire queste discrepanze. (Aggiunta 2.5.7)

Attributi specifici dei plug-in

Per informazioni dettagliate sugli attributi configurabili per ciascun plug-in, consulta la sezione Utilizzo dei plug-in.

Filtro proxy

Puoi filtrare i proxy con rilevamento del microgateway che verranno elaborati da un'istanza Edge Microgateway. All'avvio, Edge Microgateway scarica tutti i proxy con accesso sensibile al gateway nell'organizzazione a cui è associato. Utilizza la configurazione seguente per limitare i proxy che verranno elaborati dal microgateway. Ad esempio, questa configurazione limita a tre i proxy che verranno elaborati dal microgateway: edgemicro_proxy-1, edgemicro_proxy-2 e edgemicro_proxy-3:

edgemicro:
  proxies:
  - edgemicro_proxy-1
  - edgemicro_proxy-2
  - edgemicro_proxy-3

Filtrare i prodotti per nome

Utilizza la configurazione seguente per limitare il numero di prodotti API che Edge Microgateway scarica ed elabora. Per filtrare i prodotti scaricati, aggiungi il parametro di query productnamefilter all'API /products elencata nel file *.config.yaml Edge Microgateway. Ad esempio:

edge_config:
  bootstrap: >-
    https://edgemicroservices.apigee.net/edgemicro/bootstrap/organization/willwitman/environment/test
  jwt_public_key: 'https://myorg-test.apigee.net/edgemicro-auth/publicKey'
  managementUri: 'https://api.enterprise.apigee.com'
  vaultName: microgateway
  authUri: 'https://%s-%s.apigee.net/edgemicro-auth'
  baseUri: >-
    https://edgemicroservices.apigee.net/edgemicro/%s/organization/%s/environment/%s
  bootstrapMessage: Please copy the following property to the edge micro agent config
  keySecretMessage: The following credentials are required to start edge micro
  products: 'https://myorg-test.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24'

Tieni presente che il valore del parametro di query deve essere specificato nel formato di espressione regolare ed essere codificato come URL. Ad esempio, l'espressione regolare ^[Ee]dgemicro.*$ rileva nomi quali: "edgemicro-test-1" , "edgemicro_demo" e "Edgemicro_New_Demo". Il valore codificato nell'URL, adatto per essere utilizzato nel parametro di ricerca, è: %5E%5BEe%5Ddgemicro.%2A%24.

Il seguente output di debug mostra che sono stati scaricati solo i prodotti filtrati:

...
2020-05-27T03:13:50.087Z [76060] [microgateway-config network] products download from https://gsc-demo-prod.apigee.net/edgemicro-auth/products?productnamefilter=%5E%5BEe%5Ddgemicro.%2A%24 returned 200 OK
...
....
....
{
   "apiProduct":[
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590549037549,
         "createdBy":"k***@g********m",
         "displayName":"test upper case in name",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590549037549,
         "lastModifiedBy":"k***@g********m",
         "name":"Edgemicro_New_Demo",
         "proxies":[
            "catchall"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[

         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1590548328998,
         "createdBy":"k***@g********m",
         "displayName":"edgemicro test 1",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1590548328998,
         "lastModifiedBy":"k***@g********m",
         "name":"edgemicro-test-1",
         "proxies":[
            "Lets-Encrypt-Validation-DoNotDelete"
         ],
         "quota":"null",
         "quotaInterval":"null",
         "quotaTimeUnit":"null",
         "scopes":[

         ]
      },
      {
         "apiResources":[
            "/",
            "/**"
         ],
         "approvalType":"auto",
         "attributes":[
            {
               "name":"access",
               "value":"public"
            }
         ],
         "createdAt":1558182193472,
         "createdBy":"m*********@g********m",
         "displayName":"Edge microgateway demo product",
         "environments":[
            "prod",
            "test"
         ],
         "lastModifiedAt":1569077897465,
         "lastModifiedBy":"m*********@g********m",
         "name":"edgemicro_demo",
         "proxies":[
            "edgemicro-auth",
            "edgemicro_hello"
         ],
         "quota":"600",
         "quotaInterval":"1",
         "quotaTimeUnit":"minute",
         "scopes":[

         ]
      }
   ]
}

Filtrare i prodotti in base ad attributi personalizzati

Per filtrare i prodotti in base ad attributi personalizzati:

1. Nella UI di Edge, seleziona il proxy edgemicro_auth nell'organizzazione/nell'ambiente in cui hai configurato Edge Microgateway.
2. Nel tocco Sviluppa, apri il criterio JavaCallout nell'editor.
3. Aggiungi un attributo personalizzato con la chiave products.filter.attributes con un elenco di nomi degli attributi separati da virgole. Solo i prodotti che contengono uno dei nomi di attributi personalizzati verranno restituiti a Edge Microgateway.
4. Facoltativamente, puoi disabilitare il controllo per verificare se il prodotto è abilitato per l'ambiente attuale impostando l'attributo personalizzato products.filter.env.enable su false. (L'impostazione predefinita è true).
5. (Solo Private Cloud) Se ti trovi su Edge per Private Cloud, imposta la proprietà org.noncps su true per eseguire il pull dei prodotti per gli ambienti non CPS.

Ad esempio:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<JavaCallout async="false" continueOnError="false" enabled="true" name="JavaCallout">
    <DisplayName>JavaCallout</DisplayName>
    <FaultRules/>
    <Properties>
        <Property name="products.filter.attributes">attrib.one, attrib.two</Property>
        <Property name="products.filter.env.enable">false</Property>
        <Property name="org.noncps">true</Property>
    </Properties>
    <ClassName>io.apigee.microgateway.javacallout.Callout</ClassName>
    <ResourceURL>java://micro-gateway-products-javacallout-2.0.0.jar</ResourceURL>
</JavaCallout>

Configurazione della frequenza push di Analytics

Utilizza questi parametri di configurazione per controllare la frequenza con cui Edge Microgateway invia i dati di analisi ad Apigee:

• bufferSize (facoltativo): il numero massimo di record di analisi che il buffer può contenere prima di iniziare a eliminare i record meno recenti. Valore predefinito: 10.000
• batchSize (facoltativo): la dimensione massima di un batch di record di analisi inviato ad Apigee. Valore predefinito: 500
• flushInterval (facoltativo): il numero di millisecondi tra ogni svuotamento di un batch di record di analisi inviato ad Apigee. Valore predefinito: 5000

Ad esempio:

analytics:
  bufferSize: 15000
  batchSize: 1000
  flushInterval: 6000

Mascheramento dei dati di analisi

La configurazione seguente impedisce la visualizzazione delle informazioni sul percorso della richiesta nell'analisi Edge. Aggiungi quanto segue alla configurazione del microgateway per mascherare l'URI della richiesta e/o il percorso della richiesta. Tieni presente che l'URI è costituito dalle parti del nome host e del percorso della richiesta.

analytics:
  mask_request_uri: 'string_to_mask'
  mask_request_path: 'string_to_mask'

Separazione delle chiamate API in Edge Analytics

Puoi configurare il plug-in di analisi in modo da separare un percorso dell'API specifico in modo che venga visualizzato come proxy separato nelle dashboard di Edge Analytics. Ad esempio, puoi isolare un'API per il controllo di integrità nella dashboard per evitare di confonderla con le chiamate proxy API effettive. Nella dashboard di Analytics, i proxy separati seguono questo modello di denominazione:

edgemicro_proxyname-health

L'immagine seguente mostra due proxy separati nella dashboard di Analytics: edgemicro_hello-health e edgemicro_mock-health:

Utilizza questi parametri per separare i percorsi relativi e assoluti nella dashboard di Analytics come proxy separati:

• relativePath (facoltativo): specifica un percorso relativo da separare nella dashboard di Analytics. Ad esempio, se specifichi /healthcheck, tutte le chiamate API contenenti il percorso /healthcheck verranno visualizzate nella dashboard come edgemicro_proxyname-health. Tieni presente che questo flag ignora il percorso base del proxy. Per isolare in base a un percorso completo, incluso il percorso base, utilizza il flag proxyPath.
• proxyPath (facoltativo): specifica un percorso proxy API completo, incluso il percorso base del proxy, da separare nella dashboard di analisi. Ad esempio, se specifichi /mocktarget/healthcheck, dove /mocktarget è il percorso base del proxy, tutte le chiamate API con il percorso /mocktarget/healthcheck verranno visualizzate nella dashboard come edgemicro_proxyname-health.

Ad esempio, nella seguente configurazione, qualsiasi percorso API contenente /healthcheck verrà separato dal plug-in di analisi. Ciò significa che /foo/healthcheck e /foo/bar/healthcheck verranno separati come proxy separato denominato edgemicro_proxyname-health nella dashboard di analisi.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  relativePath: /healthcheck

Nella configurazione seguente, tutte le API con il percorso proxy /mocktarget/healthcheck verranno separate come proxy separato denominato edgemicro_proxyname-health nella dashboard di analisi.

analytics:
  uri: >-
    https://xx/edgemicro/ax/org/docs/environment/test
  bufferSize: 100
  batchSize: 50
  flushInterval: 500
  proxyPath: /mocktarget/healthcheck

Configurazione di Edge Microgateway protetto da un firewall aziendale

Utilizzare un proxy HTTP per la comunicazione con Apigee Edge

Aggiunto nella versione 3.1.2.

Per utilizzare un proxy HTTP per la comunicazione tra Edge Microgateway e Apigee Edge, segui questi passaggi:

1. Imposta le variabili di ambiente HTTP_PROXY, HTTPS_PROXY e NO_PROXY. Queste variabili controllano gli host per ogni proxy HTTP che vuoi utilizzare per la comunicazione con Apigee Edge o quali host non devono gestire la comunicazione con Apigee Edge. Ad esempio:

   export HTTP_PROXY='http://localhost:3786'
   export HTTPS_PROXY='https://localhost:3786'
   export NO_PROXY='localhost,localhost:8080'

   Tieni presente che NO_PROXY può essere un elenco delimitato da virgole di domini a cui Edge Microgateway non deve effettuare il proxy.

   Per ulteriori informazioni su queste variabili, consulta https://www.npmjs.com/package/request#controlling-proxy-behaviour-using-environment-variables

2. Riavvia Edge Microgateway.

Utilizza un proxy HTTP per la comunicazione di destinazione

Aggiunto nella versione 3.1.2.

Per utilizzare un proxy HTTP per la comunicazione tra Edge Microgateway e le destinazioni del backend, segui questi passaggi:

1. Aggiungi la seguente configurazione al file di configurazione del microservizio:

   edgemicro:
     proxy:
       tunnel: true | false
       url: proxy_url
       bypass: target_host # target hosts to bypass the proxy.
       enabled: true | false

   Dove:

   • tunnel: (facoltativo) se il valore è true, Edge Microgateway utilizza il metodo HTTP CONNECT per eseguire il tunneling delle richieste HTTP su una singola connessione TCP. Lo stesso vale se le variabili di ambiente, come indicato di seguito, per la configurazione del proxy sono abilitate per TLS. Valore predefinito: false
   • url: l'URL del proxy HTTP.
   • bypass: (facoltativo) specifica uno o più URL host di destinazione separati da virgole che devono bypassare il proxy HTTP. Se questa proprietà non è impostata, utilizza la variabile di ambiente NO_PROXY per specificare quali URL di destinazione ignorare.
   • enabled: se il valore è true e proxy.url è impostato, utilizza il valore proxy.url per il proxy HTTP. Se il valore true e proxy.url non è impostato, utilizza i proxy specificati nelle variabili di ambiente del proxy HTTP HTTP_PROXY e HTTPS_PROXY, come descritto in Utilizzare un proxy HTTP per la comunicazione con Apigee Edge.

   Ad esempio:

   edgemicro:
     proxy:
       tunnel: true
       url: 'http://localhost:3786'
       bypass: 'localhost','localhost:8080' # target hosts to bypass the proxy.
       enabled: true

2. Riavvia Edge Microgateway.

Utilizzo di caratteri jolly nei proxy sensibili al Microgateway

Puoi utilizzare uno o più caratteri jolly "*" nel percorso di base di un proxy edgemicro_* (microgateway-aware). Ad esempio, un percorso di base di /team/*/members consente ai client di chiamare https://[host]/team/blue/members e https://[host]/team/green/members senza dover creare nuovi proxy API per supportare i nuovi team. Tieni presente che /**/ non è supportato.

Importante: Apigee NON supporta l'utilizzo di un carattere jolly "*" come primo elemento di un percorso di base. Ad esempio, NON è supportata la ricerca di /*/.

Rotazione delle chiavi JWT

Poco tempo dopo la generazione iniziale di un JWT, potrebbe essere necessario modificare la coppia di chiavi pubblica/privata archiviata nel KVM con crittografia perimetrale. Questo processo di generazione di una nuova coppia di chiavi è chiamato rotazione della chiave.

In che modo Edge Microgateway utilizza i JWT

JSON Web Token (JWT) è uno standard di token descritto in RFC7519. JWT fornisce un modo per firmare un insieme di attestazioni, che possono essere verificate in modo affidabile dal destinatario del JWT.

Puoi generare un JWT utilizzando l'interfaccia a riga di comando e utilizzarlo nell'intestazione Authorization delle chiamate API anziché in una chiave API. Ad esempio:

curl -i http://localhost:8000/hello -H "Authorization: Bearer eyJhbGciOiJ..dXDefZEA"

Per informazioni sulla generazione di JWT con l'interfaccia a riga di comando, consulta Generare un token.

Che cos'è la rotazione della chiave?

Poco tempo dopo la generazione iniziale di un JWT, potrebbe essere necessario modificare la coppia di chiavi pubblica/privata archiviata nel KVM con crittografia perimetrale. Questo processo di generazione di una nuova coppia di chiavi è chiamato rotazione della chiave. Quando ruoti le chiavi, viene generata e archiviata una nuova coppia di chiavi privata/pubblica nel KVM "microgateway" dell'organizzazione/dell'ambiente Apigee Edge. Inoltre, la vecchia chiave pubblica viene mantenuta insieme al valore ID chiave originale.

Per generare un JWT, Edge utilizza le informazioni archiviate nel KVM criptato. Un KVM chiamato microgateway è stato creato e completato con le chiavi quando hai inizialmente configurato (configurato) Edge Microgateway. Le chiavi nel KVM vengono utilizzate per firmare e criptare un JWT.

Le chiavi KVM includono:

• private_key: la chiave privata RSA (creata più di recente) utilizzata per firmare i JWT.

• public_key - Il certificato più recente (creato più di recente) utilizzato per verificare i JWT firmati con la private_key.

• private_key_kid: l'ID della chiave privata più recente (creata più di recente). Questo ID chiave è associato al valore private_key e viene utilizzato per supportare la rotazione della chiave.

• public_key1_kid: l'ID della chiave pubblica più recente (creata più di recente). Questa chiave è associata al valore Public_key1 e viene utilizzata per supportare la rotazione delle chiavi. Questo valore corrisponde a quello del bambino della chiave privata.

• public_key1 - La chiave pubblica più recente (creata più di recente).

Quando esegui la rotazione delle chiavi, i valori delle chiavi esistenti vengono sostituiti nella mappa e vengono aggiunte nuove chiavi per conservare le chiavi pubbliche precedenti. Ad esempio:

• public_key2_kid: l'ID della chiave pubblica precedente. Questa chiave è associata al valore public_key2 e viene utilizzata per supportare la rotazione della chiave.

• public_key2 - La chiave pubblica precedente.

I JWT presentati per la verifica verranno verificati utilizzando la nuova chiave pubblica. Se la verifica non va a buon fine, verrà utilizzata la chiave pubblica precedente fino alla scadenza del JWT (dopo l'intervallo token_expiry*, il valore predefinito è 30 minuti). In questo modo, puoi "ruotare" le chiavi senza interrompere immediatamente il traffico API.

Come eseguire la rotazione della chiave

Questa sezione spiega come eseguire una rotazione della chiave.

1. Per eseguire l'upgrade del KVM, utilizza il comando edgemicro upgradekvm. Per maggiori dettagli sull'esecuzione di questo comando, consulta Upgrade del KVM. Devi eseguire questo passaggio una sola volta.
2. Per eseguire l'upgrade del proxy edgemicro-oauth, utilizza il comando edgemicro upgradeauth. Per maggiori dettagli sull'esecuzione di questo comando, consulta la pagina relativa all' upgrade del proxy edgemicro-auth. Devi eseguire questo passaggio una sola volta.
3. Aggiungi la seguente riga al file ~/.edgemicro/org-env-config.yaml, dove devi specificare la stessa organizzazione e lo stesso ambiente che hai configurato per l'utilizzo del microgateway:

   jwk_public_keys: 'https://$ORG-$ENV.apigee.net/edgemicro-auth/jwkPublicKeys'

4. Esegui il comando di rotazione delle chiavi per ruotare le chiavi. Per maggiori dettagli su questo comando, vedi Rotazione delle chiavi.

   edgemicro rotatekey -o $ORG -e $ENV -k $KEY -s $SECRET

   Ad esempio:

   edgemicro rotatekey -o docs -e test \
   -k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
   -s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47
   

Dopo la rotazione della chiave, Edge restituisce più chiavi a Edge Microgateway. Nell'esempio seguente, ogni chiave ha un valore "kid" (ID chiave) univoco. Il microgateway utilizza quindi queste chiavi per convalidare i token di autorizzazione. Se la convalida del token non va a buon fine, il microgateway controlla se nel set di chiavi è presente una chiave precedente e prova a trovarla. Il formato delle chiavi restituite è JSON Web Key (JWK). Puoi trovare informazioni su questo formato in RFC 7517.

{
  "keys": [
    {
      "kty": "RSA",
      "n": "nSl7R_0wKLiWi6cO3n8aOJwYGBtinq723Jgg8i7KKWTSTYoszOjgGsJf_MX4JEW1YCScwpE5o4o8ccQN09iHVTlIhk8CNiMZNPipClmRVjaL_8IWvMQp1iN66qy4ldWXzXnHfivUZZogCkBNqCz7VSC5rw2Jf57pdViULVvVDGwTgf46sYveW_6h8CAGaD0KLd3vZffxIkoJubh0yMy0mQP3aDOeIGf_akeZeZ6GzF7ltbKGd954iNTiKmdm8IKhz6Y3gLpC9iwQ-kex_j0CnO_daHl1coYxUSCIdv4ziWIeM3dmjQ5_2dEvUDIGG6_Az9hTpNgPE5J1tvrOHAmunQ",
      "e": "AQAB",
      "kid": "2"
    },
    {
      "kty": "RSA",
      "n": "8BKwzx34BMUcHwTuQtmp8LFRCMxbkKg_zsWD6eOMIUTAsORexTGJsTy7z-4aH0wJ3fT-3luAAUPLBQwGcuHo0P1JnbtPrpuYjaJKSZOeIMOnlryJCspmv-1xG4qAqQ9XaZ9C97oecuj7MMoNwuaZno5MvsY-oi5B_gqED3vIHUjaWCErd4reONyFSWn047dvpE6mwRhZbcOTkAHT8ZyKkHISzopkFg8CD-Mij12unxA3ldcTV7yaviXgxd3eFSD1_Z4L7ZRsDUukCJkJ-8qY2-GWjewzoxl-mAW9D1tLK6qAdc89yFem3JHRW6L1le3YK37-bs6b2a_AqJKsKm5bWw",
      "e": "AQAB",
      "kid": "1"
    }
  ]
}

Configurare un ritardo "Non prima"

Per le versioni 3.1.5 e precedenti, la nuova chiave privata generata dal comando rotatekey è entrata in vigore immediatamente e i nuovi token generati sono stati firmati con la nuova chiave privata. Tuttavia, la nuova chiave pubblica è stata resa disponibile per le istanze Edge Microgateway solo ogni 10 minuti (per impostazione predefinita) quando la configurazione del microgateway è stata aggiornata. A causa di questo ritardo tra la firma dei token e l'aggiornamento dell'istanza microgateway, i token firmati con la chiave più recente verranno rifiutati fino a quando tutte le istanze non ricevono la chiave pubblica più recente.

Nei casi in cui esistono più istanze di microgateway, il ritardo della chiave pubblica a volte causava errori di runtime intermittenti con lo stato 403, perché la convalida del token passava su un'istanza, ma non su un'altra finché non vengono aggiornate tutte le istanze.

A partire dalla versione 3.1.6, un nuovo flag nel comando rotatekey consente di specificare un ritardo prima che la nuova chiave privata diventi effettiva, consentendo l'aggiornamento di tutte le istanze del microgateway e la ricezione della nuova chiave pubblica. Il nuovo flag è --nbf, che significa "non prima". Questo flag accetta un valore intero, ovvero il numero di minuti di ritardo.

Nell'esempio seguente, il ritardo è impostato su 15 minuti:

edgemicro rotatekey -o docs -e test \
-k 27ee39567c75e4567a66236cbd4e86d1cc93df6481454301bd5fac4d3497fcbb \
-s 4618b0008a6185d7327ebf53bee3c50282ccf45a3cceb1ed9828bfbcf1148b47 \
--nbf 15

Tieni presente che è buona norma impostare il ritardo su un valore superiore all'impostazione di configurazione di config_change_poll_internal, che per impostazione predefinita è di 10 minuti. Vedi anche attributi edgemicro.

Filtro dei proxy scaricati

Per impostazione predefinita, Edge Microgateway scarica tutti i proxy nella tua organizzazione Edge che iniziano con il prefisso di denominazione "edgemicro_". Puoi modificare questa impostazione predefinita per scaricare i proxy i cui nomi corrispondono a un pattern.

1. Apri il file di configurazione Edge Micro: ~/.edgemicro/org-env-config.yaml
2. Aggiungi l'elemento proxyPattern in edge_config. Ad esempio, il seguente pattern scaricherà proxy come edgemicro_foo, edgemicro_fast ed edgemicro_first.

   edge_config:
   …
   proxyPattern: edgemicro_f*

Specifica dei prodotti senza proxy API

In Apigee Edge puoi creare un prodotto API che non contiene proxy API. Questa configurazione del prodotto consente di utilizzare una chiave API associata al prodotto con qualsiasi proxy implementato nella tua organizzazione. A partire dalla versione 2.5.4, Edge Microgateway supporta questa configurazione del prodotto.

Debug e risoluzione dei problemi

Connessione a un debugger

Puoi eseguire Edge Microgateway con un debugger, come node-inspector. Ciò è utile per la risoluzione dei problemi e il debug dei plug-in personalizzati.

1. Riavvia Edge Microgateway in modalità di debug. Per farlo, aggiungi DEBUG=* all'inizio del comando start:

   DEBUG=* edgemicro start -o $ORG -e $ENV -k $KEY -s $SECRET

   Per indirizzare l'output di debug a un file, puoi utilizzare questo comando:

   export DEBUG=* nohup edgemicro start \
   -o $ORG -e $ENV -k $KEY -s $SECRET 2>&1 | tee /tmp/file.log

2. Avvia il debugger e impostalo per l'ascolto sul numero di porta per il processo di debug.
3. Ora puoi esaminare il codice Edge Microgateway, impostare punti di interruzione, espressioni di controllo e così via.

Puoi specificare i flag Node.js standard relativi alla modalità di debug. Ad esempio, --nolazy aiuta a eseguire il debug del codice asincrono.

Controllo dei file di log

In caso di problemi, assicurati di esaminare i file di log per trovare dettagli sull'esecuzione e informazioni sugli errori. Per maggiori dettagli, vedi Gestione dei file di log.

Utilizzo della sicurezza delle chiavi API

Le chiavi API offrono un meccanismo semplice per autenticare i client che effettuano richieste a Edge Microgateway. Puoi ottenere una chiave API copiando il valore della chiave utente (detto anche ID client) da un prodotto Apigee Edge che include il proxy di autenticazione Edge Microgateway.

Memorizzazione nella cache dei tasti

Le chiavi API vengono scambiate con i token di connessione, che vengono memorizzati nella cache. Puoi disabilitare la memorizzazione nella cache impostando l'intestazione Cache-Control: no-cache sulle richieste in entrata a Edge Microgateway.

Utilizzo di una chiave API

Puoi passare la chiave API in una richiesta API come parametro di ricerca o in un'intestazione. Per impostazione predefinita, il nome del parametro di intestazione e della query sono entrambi x-api-key.

Esempio di parametro di ricerca:

curl http://localhost:8000/foobar?x-api-key=JG616Gjz7xs4t0dvpvVsGdI49G34xGsz

Esempio di titoli:

curl http://localhost:8000/foobar -H "x-api-key:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Configurazione del nome della chiave API

Per impostazione predefinita, x-api-key è il nome utilizzato sia per l'intestazione della chiave API sia per il parametro di ricerca. Puoi modificare questa impostazione predefinita nel file di configurazione, come spiegato nella sezione Apportare modifiche alla configurazione. Ad esempio, per modificare il nome in apiKey:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  api-key-header: apiKey

In questo esempio, il parametro di ricerca e il nome dell'intestazione sono stati modificati in apiKey. Il nome x-api-key non funzionerà più in nessuno dei due casi. Vedi anche Apportare modifiche alla configurazione.

Ad esempio:

curl http://localhost:8000/foobar -H "apiKey:JG616Gjz7xs4t0dvpvVsGdI49G34xGsz"

Per maggiori informazioni sull'utilizzo delle chiavi API con le richieste proxy, consulta Secure Edge Microgateway.

Attiva codici di risposta upstream

Per impostazione predefinita, il plug-in oauth restituisce solo codici di stato di errore 4xx se la risposta non è uno stato 200. Puoi modificare questo comportamento in modo che restituisca sempre il codice 4xx o 5xx esatto, a seconda dell'errore.

Per abilitare questa funzionalità, aggiungi la proprietà oauth.useUpstreamResponse: true alla configurazione del gateway perimetrale. Ad esempio:

oauth:
  allowNoAuthorization: false
  allowInvalidAuthorization: false
  gracePeriod: 10
  useUpstreamResponse: true

Utilizzo della sicurezza del token OAuth2

Questa sezione spiega come ottenere i token di accesso e i token di aggiornamento OAuth2. I token di accesso vengono utilizzati per effettuare chiamate API sicure attraverso il microgateway. I token di aggiornamento vengono utilizzati per ottenere nuovi token di accesso.

Come ottenere un token di accesso

Questa sezione spiega come utilizzare il proxy edgemicro-auth per ottenere un token di accesso.

Puoi anche ottenere un token di accesso utilizzando il comando dell'interfaccia a riga di comando edgemicro token. Per maggiori dettagli sull'interfaccia a riga di comando, vedi Gestire i token.

API 1: invia le credenziali come parametri del corpo

Sostituisci i nomi dell'organizzazione e dell'ambiente nell'URL e sostituisci i valori dell'ID e del secret del consumatore ottenuti da un'app per sviluppatori su Apigee Edge con i parametri corpo client_id e client_secret:

curl -i -X POST "http://<org>-<test>.apigee.net/edgemicro-auth/token" \
-d '{"grant_type": "client_credentials", "client_id": "your_client_id", \
"client_secret": "your_client_secret"}' -H "Content-Type: application/json"

API 2: invia le credenziali in un'intestazione Autorizzazione di base

Invia le credenziali client come intestazione dell'autenticazione di base e grant_type come parametro del modulo. Questo modulo di comando è discusso anche in RFC 6749: il framework di autorizzazione OAuth 2.0.

http://<org>-<test>.apigee.net/edgemicro-auth/token -v -u your_client_id:your_client_secret \
-d 'grant_type=client_credentials' -H "Content-Type: application/x-www-form-urlencoded"

Esempio di output

{
"token": "eyJraWQiOiIxIiwidHlwIjoi",
"access_token": "eyJraWQiOiIxIiwid",
"token_type": "bearer",
"expires_in": 1799
}

Come ottenere un token di aggiornamento

Per ottenere un token di aggiornamento, effettua una chiamata API all'endpoint /token del proxy edgemicro-auth. Devi effettuare questa chiamata API con il tipo di autorizzazione password. La procedura viene descritta di seguito.

1. Ottieni un token di accesso e aggiornamento con l'API /token. Tieni presente che il tipo di autorizzazione è password:

   curl -X POST \
     https://your_organization-your_environment.apigee.net/edgemicro-auth/token \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9oE5zLdifoDbF931TDnDtLq",
      "client_secret":"bUdDcFgv3nXffnU",
      "grant_type":"password",
      "username":"mpK6lBx9RoE5LiffoDbpF931TDnDtLq",
      "password":"bUdD2FvnMsXffnU"
   }'

   L'API restituisce un token di accesso e un token di aggiornamento. La risposta è simile a questa. Tieni presente che expires_in valorizza numeri interi e sono specificati in secondi.

   {
       "token": "your-access-token",
       "access_token": "your-access-token",
       "token_type": "bearer",
       "expires_in": 108,
       "refresh_token": "your-refresh-token",
       "refresh_token_expires_in": 431,
       "refresh_token_issued_at": "1562087304302",
       "refresh_token_status": "approved"
   }

2. Ora puoi utilizzare il token di aggiornamento per ottenere un nuovo token di accesso chiamando l'endpoint /refresh della stessa API. Ad esempio:

   curl -X POST \
     https://willwitman-test.apigee.net/edgemicro-auth/refresh \
     -H 'Content-Type: application/json' \
     -d '{
      "client_id":"mpK6l1Bx9RoE5zLifoDbpF931TDnDtLq",
      "client_secret":"bUdDc2Fv3nMXffnU",
      "grant_type":"refresh_token",
      "refresh_token":"your-refresh-token"
   }'

   L'API restituisce un nuovo token di accesso. La risposta è simile alla seguente:

   {
       "token": "your-new-access-token"
       }

Monitoraggio costante

Forever è uno strumento Node.js che riavvia automaticamente un'app Node.js nel caso in cui il processo non vada a buon fine o si verifichi un errore. Edge Microgateway ha un file forever.json che puoi configurare per controllare quante volte e con quali intervalli Edge Microgateway deve essere riavviato. Questo file configura un servizio Forever denominato forever-monitor, che gestisce Forever in modo programmatico.

Puoi trovare il file forever.json nella directory di installazione root di Edge Microgateway. Vedi Dove è installato Edge Microgateway. Per maggiori dettagli sulle opzioni di configurazione, consulta la documentazione di Forever-Monitor.

Il comando edgemicro forever include flag che consentono di specificare la posizione del file forever.json (il flag -f) e di avviare/interrompere il processo di monitoraggio continuo (il flag -a). Ad esempio:

edgemicro forever -f ~/mydir/forever.json -a start

Per ulteriori informazioni, consulta la sezione Monitoraggio permanente nel riferimento dell'interfaccia a riga di comando.

Specifica di un endpoint del file di configurazione

Se esegui più istanze Edge Microgateway, potresti voler gestire le relative configurazioni da un'unica località. Puoi farlo specificando un endpoint HTTP in cui Edge Micro può scaricare il proprio file di configurazione. Puoi specificare questo endpoint quando avvii Edge Micro utilizzando il flag -u.

Ad esempio:

edgemicro start -o jdoe -e test -u http://mylocalserver/mgconfig -k public_key -s secret_key

dove l'endpoint mgconfig restituisce i contenuti del file di configurazione. Questo è il file che, per impostazione predefinita, si trova in ~/.edgemicro e ha la convenzione di denominazione: org-env-config.yaml.

Disabilitazione del buffering dei dati della connessione TCP

Puoi utilizzare l'attributo di configurazione nodelay per disabilitare il buffering dei dati per le connessioni TCP utilizzate da Edge Microgateway.

Per impostazione predefinita, le connessioni TCP utilizzano l'algoritmo Nagle per eseguire il buffering dei dati prima di inviarli. L'impostazione di nodelay su true disattiva questo comportamento (i dati verranno attivati immediatamente dopo ogni chiamata a socket.write()). Per ulteriori dettagli, consulta anche la documentazione relativa a Node.js.

Per attivare nodelay, modifica il file di configurazione della micro configurazione Edge come segue:

edgemicro:
  nodelay: true
  port: 8000
  max_connections: 1000
  config_change_poll_interval: 600
  logging:
    level: error
    dir: /var/tmp
    stats_log_interval: 60
    rotate_interval: 24

Esecuzione di Edge Microgateway in modalità autonoma

Puoi eseguire Edge Microgateway completamente disconnesso da qualsiasi dipendenza Apigee Edge. Questo scenario, chiamato modalità autonoma, consente di eseguire e testare Edge Microgateway senza una connessione a internet.

In modalità autonoma, le seguenti funzionalità non funzionano, poiché richiedono la connessione ad Apigee Edge:

• OAuth e chiave API
• Quota
• Analytics

D'altra parte, i plug-in personalizzati e l'arresto dei picchi funzionano normalmente perché non richiedono una connessione ad Apigee Edge. Inoltre, un nuovo plug-in extauth consente di autorizzare le chiamate API al microgateway con un JWT in modalità autonoma.

Configurazione e avvio del gateway

Per eseguire Edge Microgateway in modalità autonoma:

1. Crea un file di configurazione denominato come segue: $HOME/.edgemicro/$ORG-$ENV-config.yaml

   Ad esempio:

   vi $HOME/.edgemicro/foo-bar-config.yaml

2. Incolla il codice seguente nel file:

   edgemicro:
     port: 8000
     max_connections: 1000
     config_change_poll_interval: 600
     logging:
       level: error
       dir: /var/tmp
       stats_log_interval: 60
       rotate_interval: 24
     plugins:
       sequence:
         - extauth
         - spikearrest
   headers:
     x-forwarded-for: true
     x-forwarded-host: true
     x-request-id: true
     x-response-time: true
     via: true
   extauth:
     publickey_url: https://www.googleapis.com/oauth2/v1/certs
   spikearrest:
     timeUnit: second
     allow: 10
     buffersize: 0

3. Esporta la seguente variabile di ambiente con il valore "1":

   export EDGEMICRO_LOCAL=1

4. Esegui questo comando start, in cui devi fornire i valori per creare un'istanza del proxy locale:

   edgemicro start -o $ORG -e $ENV -a $LOCAL_PROXY_NAME \
     -v $LOCAL_PROXY_VERSION -t $TARGET_URL -b $BASE_PATH

   Dove:

   • $ORG è il nome "organizzazione" che hai utilizzato nel nome del file di configurazione.
   • $ENV è il nome "env" utilizzato nel nome del file di configurazione.
   • $LOCAL_PROXY_NAME è il nome del proxy locale che verrà creato. Puoi utilizzare il nome che preferisci.
   • $LOCAL_PROXY_VERSION è il numero di versione del proxy.
   • $TARGET_URL è l'URL del target del proxy. Il target è il servizio chiamato dal proxy.
   • $BASE_PATH è il percorso di base del proxy. Questo valore deve iniziare con una barra. Per un percorso di base principale, specifica solo una barra, ad esempio "/".

   Ad esempio:

   edgemicro start -o local -e test -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

5. Testa la configurazione.

   curl http://localhost:8000/echo  { "error" : "missing_authorization" }

   Poiché il plug-in extauth si trova nel file foo-bar-config.yaml, ricevi un errore "missing_Authorization". Questo plug-in convalida un JWT che deve essere presente nell'intestazione Authorization della chiamata API. Nella sezione successiva, otterrai un JWT che consentirà l'esecuzione delle chiamate API senza l'errore.

Esempio: ottenere un token di autorizzazione

L'esempio seguente mostra come ottenere un JWT dall'endpoint JWT Edge Microgateway su Apigee Edge (edgemicro-auth/jwkPublicKeys). Il deployment di questo endpoint viene eseguito quando esegui una configurazione e una configurazione standard di Edge Microgateway. Per ottenere il JWT dall'endpoint Apigee, devi prima eseguire la configurazione standard di Edge Microgateway ed essere connesso a internet. L'endpoint Apigee viene utilizzato qui solo a scopo di esempio e non è obbligatorio. Se vuoi, puoi utilizzare un altro endpoint del token JWT. In questo caso, dovrai ottenere il JWT utilizzando l'API fornita per quell'endpoint.

I passaggi seguenti spiegano come ottenere un token utilizzando l'endpoint edgemicro-auth/jwkPublicKeys:

1. Devi eseguire una configurazione standard di Edge Microgateway per eseguire il deployment del proxy edgemicro-auth nel tuo ambiente o nella tua organizzazione su Apigee Edge. Se hai già eseguito questo passaggio, non è necessario ripeterlo.
2. Se hai eseguito il deployment di Edge Microgateway in Apigee Cloud, devi disporre di una connessione a internet per poter ottenere un JWT da questo endpoint.
3. Interrompi il microgateway Edge:

   edgemicro stop

4. Nel file di configurazione creato in precedenza ($HOME/.edgemicro/org-env-config.yaml), punta l'attributo extauth:publickey_url all'endpoint edgemicro-auth/jwkPublicKeys nel tuo ambiente/organizzazione Apigee Edge. Ad esempio:

   extauth:
     publickey_url: 'https://your_org-your_env.apigee.net/edgemicro-auth/jwkPublicKeys'

5. Riavvia Edge Microgateway come hai fatto in precedenza, utilizzando i nomi organizzazione/ambiente utilizzati nel nome del file di configurazione. Ad esempio:

   edgemicro start -o foo -e bar -a proxy1 -v 1 -t http://mocktarget.apigee.net -b /

6. Recupera un token JWT dall'endpoint di autorizzazione. Poiché stai utilizzando l'endpoint edgemicro-auth/jwkPublicKeys, puoi utilizzare questo comando dell'interfaccia a riga di comando:

Puoi generare un JWT per Edge Microgateway utilizzando il comando edgemicro token o un'API. Ad esempio:

edgemicro token get -o your_org -e your_env \
  -i G0IAeU864EtBo99NvUbn6Z4CBwVcS2 -s uzHTbwNWvoSmOy

Dove:

• your_org è il nome della tua organizzazione Apigee per cui hai precedentemente configurato Edge Microgateway.
• your_env è un ambiente dell'organizzazione.
• L'opzione i specifica la chiave utente di un'app per sviluppatori che ha un prodotto che include il proxy edgemicro-auth.
• L'opzione s specifica il consumer secret di un'app per sviluppatori che dispone di un prodotto che include il proxy edgemicro-auth.

Questo comando chiede ad Apigee Edge di generare un JWT che può essere utilizzato per verificare le chiamate API.

Testa la configurazione autonoma

Per testare la configurazione, chiama l'API con il token aggiunto nell'intestazione Authorization come segue:

curl http://localhost:8000/echo -H "Authorization: Bearer your_token

Esempio:

curl http://localhost:8000/echo -H "Authorization: Bearer eyJraWQiOiIxIiwidHlwIjo...iryF3kwcDWNv7OQ"

Output di esempio:

{
   "headers":{
      "user-agent":"curl/7.54.0",
      "accept":"*/*",
      "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
      "client_received_start_timestamp":"1535134472699",
      "x-authorization-claims":"eyJhdDbiO...M1OTE5MTA1NDkifQ==",
      "target_sent_start_timestamp":"1535134472702",
      "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
      "x-forwarded-proto":"http",
      "x-forwarded-host":"localhost:8000",
      "host":"mocktarget.apigee.net",
      "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
      "via":"1.1 localhost, 1.1 google",
      "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
      "connection":"Keep-Alive"
   },
   "method":"GET",
   "url":"/",
   "body":""
}

Utilizzo della modalità proxy locale

In modalità proxy locale, Edge Microgateway non richiede il deployment di un proxy microgateway-aware su Apigee Edge. Devi invece configurare un "proxy locale" fornendo il nome del proxy locale, il percorso base e l'URL di destinazione all'avvio del microgateway. Le chiamate API al microgateway vengono quindi inviate all'URL di destinazione del proxy locale. Sotto tutti gli altri aspetti, la modalità proxy locale funziona esattamente come l'esecuzione di Edge Microgateway nella modalità normale. L'autenticazione funziona allo stesso modo, così come l'arresto dei picchi e l'applicazione delle quote, i plug-in personalizzati e così via.

Caso d'uso ed esempio

La modalità proxy locale è utile quando devi associare un solo proxy a un'istanza Edge Microgateway. Ad esempio, puoi inserire Edge Microgateway in Kubernetes come proxy sidecar, dove un microgateway e un servizio vengono eseguiti ognuno in un unico pod e dove il microgateway gestisce il traffico da e verso il suo servizio companion. La figura seguente illustra questa architettura in cui Edge Microgateway funziona come proxy sidecar in un cluster Kubernetes. Ogni istanza di microgateway comunica solo con un singolo endpoint nel proprio servizio companion:

Uno dei vantaggi di questo stile di architettura è che Edge Microgateway fornisce la gestione delle API per singoli servizi di cui è stato eseguito il deployment in un ambiente container, ad esempio un cluster Kubernetes.

Configurazione della modalità proxy locale

Per configurare Edge Microgateway in modo che venga eseguito in modalità proxy locale, segui questi passaggi:

1. Esegui edgemicro init per configurare il tuo ambiente di configurazione locale, esattamente come faresti in una tipica configurazione di Edge Microgateway. Vedi anche Configurare Edge Microgateway.
2. Esegui edgemicro configure, come faresti in una tipica procedura di configurazione di Edge Microgateway. Ad esempio:

   edgemicro configure -o your_org -e your_env -u your_apigee_username

   Questo comando esegue il deployment del criterio edgemicro-auth su Edge e restituisce una chiave e un secret necessari per avviare il microgateway. Se hai bisogno di aiuto, consulta Configurare Edge Microgateway.

3. Su Apigee Edge, crea un prodotto API e con i seguenti requisiti di configurazione obbligatori (puoi gestire tutte le altre configurazioni come preferisci):
   • Devi aggiungere il proxy edgemicro-auth al prodotto. Il deployment di questo proxy è stato eseguito automaticamente quando hai eseguito edgemicro configure.
   • Devi fornire un percorso della risorsa. Apigee consiglia di aggiungere questo percorso al prodotto: /**. Per saperne di più, vedi Configurazione del comportamento del percorso della risorsa. Vedi anche Creare prodotti API nella documentazione di Edge.

4. Su Apigee Edge, crea uno sviluppatore o, se vuoi, puoi utilizzarne uno esistente. Per informazioni, consulta Aggiungere sviluppatori utilizzando l'interfaccia utente di gestione perimetrale.

5. Su Apigee Edge, crea un'app sviluppatore. Devi aggiungere all'app il prodotto API appena creato. Per assistenza, consulta Registrare un'app nell'interfaccia utente di gestione di Edge.
6. Sulla macchina in cui è installato Edge Microgateway, esporta la seguente variabile di ambiente con il valore "1".

   export EDGEMICRO_LOCAL_PROXY=1

7. Esegui questo comando start:

   edgemicro start -o your_org -e your_environment -k your_key -s your_secret \
       -a local_proxy_name -v local_proxy_version -t target_url -b base_path

   Dove:

   • your_org è la tua organizzazione Apigee.
   • your_environment è un ambiente della tua organizzazione.
   • your_key è la chiave restituita quando hai eseguito edgemicro configure.
   • your_secret è il secret restituito quando hai eseguito edgemicro configure.
   • local_proxy_name è il nome del proxy locale che verrà creato.
   • local_proxy_version è il numero di versione del proxy.
   • target_url è l'URL della destinazione del proxy (il servizio che verrà chiamato dal proxy).
   • base_path è il percorso di base del proxy. Questo valore deve iniziare con una barra. Per un percorso di base principale, specifica solo una barra, ad esempio "/".

   Ad esempio:

   edgemicro start -o your_org -e test -k 7eb6aae644cbc09035a...d2eae46a6c095f \
     -s e16e7b1f5d5e24df...ec29d409a2df853163a -a proxy1 -v 1 \
     -t http://mocktarget.apigee.net -b /echo

Test della configurazione

Puoi testare la configurazione del proxy locale chiamando l'endpoint del proxy. Ad esempio, se hai specificato un percorso base /echo, puoi chiamare il proxy come segue:

curl  http://localhost:8000/echo
{
  "error" : "missing_authorization",
  "error_description" : "Missing Authorization header"
}

Questa chiamata API iniziale ha generato un errore perché non hai fornito una chiave API valida. Puoi trovare la chiave nell'app sviluppatore che hai creato in precedenza. Apri l'app nell'interfaccia utente perimetrale, copia la chiave utente e utilizzala come segue:

curl  http://localhost:8000/echo -H 'x-api-key:your_api_key'

Ad esempio:

curl  http://localhost:8000/echo -H "x-api-key:DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP"

Output di esempio:

{
  "headers":{
    "user-agent":"curl/7.54.0",
    "accept":"*/*",
    "x-api-key":"DvUdLlFwG9AvGGpEgfnNGwtvaXIlUUvP",
    "client_received_start_timestamp":"1535134472699",
    "x-authorization-claims":"eyJhdWQiOi...TQ0YmUtOWNlOS05YzM1OTE5MTA1NDkifQ==",
    "target_sent_start_timestamp":"1535134472702",
    "x-request-id":"678e3080-a7ae-11e8-a70f-87ae30db3896.8cc81cb0-a7c9-11e8-a70f-87ae30db3896",
    "x-forwarded-proto":"http",
    "x-forwarded-host":"localhost:8000",
    "host":"mocktarget.apigee.net",
    "x-cloud-trace-context":"e2ac4fa0112c2d76237e5473714f1c85/1746478453618419513",
    "via":"1.1 localhost, 1.1 google",
    "x-forwarded-for":"::1, 216.98.205.223, 35.227.194.212",
    "connection":"Keep-Alive"
  },
  "method":"GET",
  "url":"/",
  "body":""
}

Utilizzo del sincronizzatore

Questa sezione spiega come utilizzare il sincronizzatore, una funzionalità facoltativa che migliora la resilienza di Edge Microgteway consentendo di recuperare i dati di configurazione da Apigee Edge e scriverli in un database Redis locale. Quando è in esecuzione un'istanza del sincronizzatore, le altre istanze Edge Microgateway in esecuzione su nodi diversi possono recuperare la propria configurazione direttamente da questo database.

La funzionalità di sincronizzazione è attualmente supportata per funzionare con Redis 5.0.x.

Che cos'è il sincronizzatore?

Il sincronizzatore fornisce un livello di resilienza per Edge Microgateway. Contribuisce a garantire che ogni istanza di Edge Microgateway utilizzi la stessa configurazione e che, in caso di interruzione della connessione a internet, le istanze di Edge Microgateway possano essere avviate ed eseguite correttamente.

Per impostazione predefinita, le istanze Edge Microgateway devono essere in grado di comunicare con Apigee Edge per recuperare e aggiornare i dati di configurazione, ad esempio i proxy API e le configurazioni dei prodotti API. Se la connessione a internet con Edge viene interrotta, le istanze di microgateway possono continuare a funzionare perché vengono memorizzati nella cache i dati di configurazione più recenti. Tuttavia, le nuove istanze di microgateway non possono essere avviate senza una connessione chiara. Inoltre, è possibile che un'interruzione della connessione a internet comporti una o più istanze di microgateway in esecuzione con informazioni di configurazione non sincronizzate con le altre istanze.

Il sincronizzatore Edge Microgateway fornisce un meccanismo alternativo per consentire alle istanze Edge Microgateway di recuperare i dati di configurazione necessari per l'avvio e l'elaborazione del traffico proxy API. I dati di configurazione recuperati dalle chiamate ad Apigee Edge includono: la chiamata jwk_public_keys, la chiamata jwt_public_key, la chiamata bootstrap e la chiamata dei prodotti API. Il sincronizzatore consente a tutte le istanze di Edge Microgateway in esecuzione su nodi diversi di avviarsi correttamente e rimanere sincronizzate anche in caso di interruzione della connessione a internet tra Edge Microgateway e Apigee Edge.

Il sincronizzatore è un'istanza appositamente configurata di Edge Microgateway. Il suo unico scopo è eseguire il polling di Apigee Edge (la sincronizzazione è configurabile), recuperare i dati di configurazione e scriverli in un database Redis locale. L'istanza del sincronizzatore non può elaborare il traffico proxy API. Altre istanze di Edge Microgateway in esecuzione su nodi diversi possono essere configurate per recuperare i dati di configurazione dal database Redis anziché da Apigee Edge. Poiché tutte le istanze di microgateway estraggono i propri dati di configurazione dal database locale, possono avviare ed elaborare le richieste API anche in caso di interruzione della connessione a internet.

Configurazione di un'istanza del sincronizzatore

Aggiungi la seguente configurazione al file org-env/config.yaml per l'installazione di Edge Microgateway che vuoi utilizzare come sincronizzatore:

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Ad esempio:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 1
  redisBasedConfigCache: true

Infine, salva il file di configurazione e avvia l'istanza Edge Microgateway. Inizierà il polling di Apigee Edge e l'archiviazione dei dati di configurazione scaricati nel database Redis.

Configurazione di istanze regolari Edge Microgateway

Quando il sincronizzatore è in esecuzione, puoi configurare altri nodi Edge Microgateway per eseguire normali istanze di microgateway che elaborano il traffico proxy API. Tuttavia, configurerai queste istanze per ottenere i relativi dati di configurazione dal database Redis anziché da Apigee Edge.

Aggiungi la configurazione seguente a ciascun file org-env/config.yaml aggiuntivo del nodo Edge Microgateway. Tieni presente che la proprietà synchronizerMode è impostata su 0. Questa proprietà imposta l'istanza in modo che funzioni come una normale istanza Microgateway perimetrale che elabora il traffico proxy API. L'istanza otterrà i dati di configurazione dal database Redis.

edgemicro:
  redisHost: host_IP
  redisPort: host_port
  redisDb: database_index
  redisPassword: password
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Ad esempio:

edgemicro:
  redisHost: 192.168.4.77
  redisPort: 6379
  redisDb: 0
  redisPassword: codemaster
edge_config:
  synchronizerMode: 0
  redisBasedConfigCache: true

Proprietà di configurazione

Per supportare l'utilizzo del sincronizzatore, sono state aggiunte le seguenti proprietà di configurazione:

Configurazione di URL di esclusione per i plug-in

Puoi configurare il microgateway in modo da saltare l'elaborazione dei plug-in per gli URL specificati. Puoi configurare questi URL "esclusi" a livello globale (per tutti i plug-in) o per plug-in specifici.

Ad esempio:

...
edgemicro:
  ...
  plugins:
    excludeUrls: '/hello,/proxy_one' # global exclude urls
    sequence:
      - oauth
      - json2xml
      - quota
json2xml:
  excludeUrls: '/hello/xml'  # plugin level exclude urls
...

In questo esempio, i plug-in non elaborano le chiamate proxy API in entrata con i percorsi /hello o /proxy_one. Inoltre, il plug-in json2xml verrà ignorato per le API il cui percorso è /hello/xml.

Impostare gli attributi di configurazione con valori delle variabili di ambiente

Puoi specificare le variabili di ambiente utilizzando i tag nel file di configurazione. I tag delle variabili di ambiente specificati vengono sostituiti dai valori effettivi delle variabili di ambiente. Le sostituzioni vengono memorizzate solo in memoria e non nei file di configurazione o cache originali.

In questo esempio, l'attributo key viene sostituito dal valore della variabile di ambiente TARGETS_SSL_CLIENT_KEY e così via.

targets:
  - ssl:
      client:
        key: <E>TARGETS_SSL_CLIENT_KEY</E>
        cert: <E>TARGETS_SSL_CLIENT_CERT</E>
        passphrase: <E>TARGETS_SSL_CLIENT_PASSPHRASE</E>

In questo esempio, il tag <n> viene utilizzato per indicare un valore intero. Sono supportati solo numeri interi positivi.

edgemicro:
  port: <E><n>EMG_PORT</n></E>

In questo esempio, il tag <b> viene utilizzato per indicare un valore booleano (vale a dire true o false).

quotas:
  useRedis: <E><b>EMG_USE_REDIS</b></E>