Utilizzo di JWT per autenticare gli utenti

In questa pagina viene descritto come supportare l'autenticazione utente in API Gateway.

Per autenticare un utente, un'applicazione client deve inviare un JSON Web Token (JWT) nell'intestazione di autorizzazione del file HTTP all'API backend. API Gateway convalida il token per conto della tua API, quindi non devi aggiungere alcun codice alla tua API per elaborare l'autenticazione. Tuttavia, devi configurare il Configurazione API per il gateway in modo da supportare i metodi di autenticazione scelti.

API Gateway convalida un JWT in modo efficiente utilizzando il protocollo JSON Web Key Set (JWKS) dell'emittente. La località del JWKS è specificata nel campo x-google-jwks_uri della configurazione API del gateway. API Gateway memorizza nella cache il file JWKS per cinque minuti e lo aggiorna ogni cinque minuti.

Prima di iniziare

  • Aggiungi il codice di autenticazione all'applicazione client seguendo la documentazione del fornitore di autenticazione.

  • Quando l'applicazione client invia una richiesta HTTP, l'intestazione di autorizzazione nella richiesta deve contenere i seguenti claim JWT:
    • iss (emittente)
    • sub (soggetto)
    • aud (pubblico)
    • iat (emissione:)
    • exp (data/ora di scadenza)

Configurare API Gateway per supportare l'autenticazione client

Devi disporre di un requisito e un oggetto Definizioni dell'oggetto nella configurazione API per API Gateway per le attestazioni nel JWT firmato.

Per supportare l'autenticazione JWT:

  1. Aggiungi quanto segue alla definizione di sicurezza nella configurazione dell'API, che segue lo schema di sicurezza OpenAPI 2.0:

     securityDefinitions:
   your_custom_auth_id:
     authorizationUrl: ""
     flow: "implicit"
     type: "oauth2"
     # The value below should be unique
     x-google-issuer: "issuer of the token"
     x-google-jwks_uri: "url to the public key"
     # Optional. Replace YOUR-CLIENT-ID with your client ID
     x-google-audiences: "YOUR-CLIENT-ID"

  2. Aggiungi una sezione di sicurezza a livello di API da applicare all'intera API o a livello di metodo da applicare a un metodo specifico.

     security:
   - your_custom_auth_id: []

Puoi definire più definizioni di sicurezza nella configurazione dell'API, ma ogni definizione deve avere un emittente diverso. Se utilizzi sezioni di sicurezza sia a livello di API sia a livello di metodo, le impostazioni a livello di metodo sostituiscono quelle a livello di API.

Il campo x-google-audiences non è obbligatorio. Gateway API accetta tutti i JWT con il nome del servizio di backend sotto forma di https://SERVICE_NAME nella rivendicazione aud.

Per consentire a ID client aggiuntivi di accedere al servizio di backend, puoi specificare ID cliente consentiti nel campo x-google-audiences utilizzando separati da virgole. API Gateway accetta quindi i JWT con uno qualsiasi dei ID cliente specificati nella rivendicazione aud.

Il campo x-google-jwks_uri è obbligatorio. API Gateway supporta due formati di chiave pubblica asimmetrica definiti dall'estensione OpenAPI x-google-jwks_uri:

  • Formato impostato JWK. Ad esempio: 
    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Ad esempio: 
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Se utilizzi un formato di chiave simmetrica, imposta x-google-jwks_uri sull'URI di un file contenente la stringa della chiave codificata in base64url.

Effettuare una chiamata autenticata a un'API API Gateway

Quando invii una richiesta utilizzando un token di autenticazione, ti consigliamo di inserire il token nell'intestazione Authorization:Bearer. Ad esempio:

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

Qui, GATEWAY_URL e TOKEN sono variabili di ambiente contenenti rispettivamente l'URL del gateway di cui è stato eseguito il deployment e il token di autenticazione. Consulta Effettuare una richiesta autenticata a un'API API Gateway per un codice campione che invia una richiesta utilizzando l'intestazione Authorization:Bearer.

Se non puoi utilizzare l'intestazione quando invii la richiesta, puoi inserire il in un parametro di query chiamato access_token. Ad esempio:

curl "${GATEWAY_URL}/echo?access_token=${TOKEN}"

Ricevere risultati autenticati nell'API

In genere, API Gateway inoltra tutte le intestazioni che riceve. Tuttavia, sostituisce il l'intestazione Authorization originale quando l'indirizzo di backend è specificato da x-google-backend nella configurazione API.

API Gateway invierà il risultato dell'autenticazione in X-Apigateway-Api-Userinfo all'API di backend. Ti consigliamo di utilizzare questa intestazione anziché l'originale Intestazione Authorization. Questa intestazione è codificata in base64url e contiene il payload JWT.

Passaggi successivi