Utilizzo di token ID Google personalizzati per autenticare gli utenti

Questa pagina descrive come supportare l'autenticazione utente in Cloud Endpoints.

Per autenticare un utente, un'applicazione client deve inviare un token JWT (JSON Web Token) nell'intestazione di autorizzazione della richiesta HTTP all'API di backend. Extensible Service Proxy (ESP) 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 documento OpenAPI in modo che supporti i metodi di autenticazione che hai scelto.

L'ESP convalida un JWT in modo efficiente utilizzando le chiavi pubbliche dell'emittente del JWT. ESP memorizza nella cache le chiavi pubbliche per cinque minuti. Inoltre, ESP memorizza nella cache i JWT convalidati per cinque minuti o fino alla scadenza del JWT, a seconda dell'evento che si verifica per primo.

Prima di iniziare

  • Aggiungi all'applicazione client il codice di autenticazione che consente agli utenti di autenticharsi accedendo con l'Account Google.

  • 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 (rilasciato il giorno)
    • exp (data/ora di scadenza)

Configurare l'ESP per supportare l'autenticazione client

Per consentire a ESP di convalidare i claim nel JWT firmato, devi avere un oggetto security requirement e un oggetto security definitions nel documento OpenAPI.

Per supportare l'autenticazione utilizzando un token ID Google:

  1. Aggiungi quanto segue alla definizione di sicurezza nel documento OpenAPI:

      securityDefinitions:
    google_id_token:
      authorizationUrl: ""
      flow: "implicit"
      type: "oauth2"
      x-google-issuer: "https://accounts.google.com"
      x-google-jwks_uri: "https://www.googleapis.com/oauth2/v3/certs"
      # 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:
    - google_id_token: []

Puoi definire più definizioni di sicurezza nel documento OpenAPI, 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. ESP accetta tutti i JWT con il nome del servizio di backend sotto forma di https://SERVICE_NAME nel claim aud. Per consentire a ID client aggiuntivi di accedere al servizio di backend, puoi specificare gli ID client consentiti nel campo x-google-audiences utilizzando valori separati da virgola. L'ESP accetta quindi i JWT con uno degli ID cliente specificati nel claim aud.

Puoi anche personalizzare le posizioni JWT aggiungendo x-google-extensions. Per maggiori dettagli, vedi Estensioni openAPI.

Eseguire una chiamata autenticata a un'API Endpoints

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

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

Qui, ENDPOINTS_HOST e TOKEN sono variabili di ambiente contenenti rispettivamente il nome dell'host dell'API e il token di autenticazione. Consulta Eseguire una richiesta autenticata a un'API Endpoints. per il 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 "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

Ricevere i risultati dell'autenticazione nell'API

In genere, l'ESP inoltra tutte le intestazioni che riceve. Tuttavia, sostituisce l'Authorization originale quando l'indirizzo del backend è specificato da x-google-backend nella specifica OpenAPI o da BackendRule nella configurazione del servizio gRPC.

L'ESP invierà il risultato dell'autenticazione in X-Endpoint-API-UserInfo all'API di backend. Ti consigliamo di utilizzare questa intestazione anziché l'intestazioneAuthorization originale. Questa intestazione è una stringa che base64url codifica un oggetto JSON. Il formato dell'oggetto JSON è diverso tra ESPv2 ed ESP. Per ESPv2, l'oggetto JSON è esattamente il payload JWT originale. Per ESP, l'oggetto JSON utilizza nomi di campo diversi e inserisce il payload JWT originale nel campo claims. Per ulteriori informazioni sul formato, consulta Gestire i token JWT nel servizio di backend.

Passaggi successivi