Utilizzo di JWT per autenticare gli utenti

Questa pagina descrive come supportare l'autenticazione utente in API Gateway.

Per autenticare un utente, un'applicazione client deve inviare un token web JSON (JWT) nell'intestazione di autorizzazione della richiesta HTTP alla tua API di backend. API Gateway convalida il token per conto della tua API, quindi non devi aggiungere codice alla tua API per elaborare l'autenticazione. Tuttavia, devi configurare la configurazione API per il gateway in modo che supporti i metodi di autenticazione scelti.

API Gateway convalida un JWT in modo efficiente utilizzando il set di chiavi web JSON (JWKS) dell'emittente JWT. La posizione del JWKS è specificata nella configurazione API del gateway. API Gateway memorizza nella cache 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 provider di autenticazione.

  • Quando l'applicazione client invia una richiesta HTTP, l'intestazione di autorizzazione nella richiesta deve contenere le seguenti rivendicazioni JWT:
    • iss (emittente)
    • sub (oggetto)
    • aud (pubblico)
    • iat (emesso il giorno)
    • exp (data/ora di scadenza)

Configurare API Gateway per supportare l'autenticazione client

Per consentire ad API Gateway di convalidare le rivendicazioni nel JWT firmato, devi includere una sezione di sicurezza nella configurazione API. Lo schema utilizzato per definire i metodi di sicurezza dipende dalla versione della specifica OpenAPI che utilizzi.

Per supportare l'autenticazione JWT:

OpenAPI 2.0

  1. Aggiungi quanto segue alla configurazione API: 
    securityDefinitions:
  your_custom_auth_id:
    authorizationUrl: ""
    flow: "implicit"
    type: "oauth2"
    # The issuer value should be unique
    x-google-issuer: "ISSUER"
    x-google-jwks_uri: "URL_PUBLIC_KEY"
    # Optional.
    x-google-audiences: "CLIENT_ID"

    Dove:

    • ISSUER è l'emittente del token.
    • URL_PUBLIC_KEY è l'URL della chiave pubblica.
    • CLIENT_ID è l'ID client.
  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: []

OpenAPI 3.x

  1. Aggiungi quanto segue alla configurazione API: 
    components:
  securitySchemes:
    SCHEME_NAME:
      type: oauth2
      flows:
       implicit:
         authorizationUrl: ""
         scopes: {}
      x-google-auth:
        issuer: ISSUER
        jwksUri: URL_PUBLIC_KEY
        # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings.
        audiences:
          - CLIENT_ID
        jwtLocations:
          - header: Authorization
            valuePrefix: "Bearer "

    Dove:

    • ISSUER è l'emittente del token.
    • URL_PUBLIC_KEY è l'URL della chiave pubblica.
    • CLLIENT_ID è un elenco di ID client come stringhe.
  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:
  - SCHEME_NAME: []

Puoi definire più definizioni di sicurezza nella configurazione 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 (OpenAPI 2.0) o audiences (OpenAPI 3.x) non è obbligatorio. API Gateway accetta tutti i JWT con il nome del servizio di backend nel formato https://SERVICE_NAME nella rivendicazione aud.

Per consentire a ID client aggiuntivi di accedere al servizio di backend, puoi specificare gli ID client consentiti nel campo audiences applicabile. Più segmenti di pubblico vengono specificati come valori separati da virgole in OpenAPI 2.0 e con un elenco in OpenAPI 3.x. utilizzando valori separati da virgole. API Gateway accetta quindi i JWT con uno qualsiasi degli ID client specificati nella rivendicazione aud.

Il campo x-google-jwks_uri (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) è obbligatorio. API Gateway supporta due formati di chiave pubblica asimmetrica definiti da questa estensione OpenAPI:

  • Formato del set JWK. Ad esempio:

    OpenAPI 2.0

    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Ad esempio:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    jwksUri: "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 (OpenAPI 2.0) o jwksUri (OpenAPI 3.x) sull'URI di un file che contiene la stringa della chiave codificata in base64url.

Esegui 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 -H "Authorization: Bearer TOKEN" "GATEWAY_URL/hello"

Qui, GATEWAY_URL e TOKEN devono essere sostituiti rispettivamente con l'URL del gateway di cui è stato eseguito il deployment e il token di autenticazione. Consulta Eseguire 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 token di autenticazione in un parametro di query denominato access_token. Ad esempio: 

curl "GATEWAY_URL/hello?access_token=TOKEN"

Ricevere risultati autenticati nell'API

API Gateway in genere inoltra tutte le intestazioni che riceve. Tuttavia, esegue l'override dell'intestazione Authorization originale quando l'indirizzo 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'intestazione Authorization originale. Questa intestazione è codificata in base64url e contiene il payload JWT.

Passaggi successivi