Utilizzo di un metodo personalizzato 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 web JSON (JWT) nell'intestazione di autorizzazione della richiesta HTTP alla tua API di backend. Extensible Service Proxy (ESP) convalida il token per conto della tua API, quindi non devi aggiungere codice alla tua API per elaborare l'autenticazione. Tuttavia, devi configurare il documento OpenAPI per supportare i metodi di autenticazione scelti.

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 di quale si verifica per primo.

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)

Configurazione di ESP per supportare l'autenticazione client

Devi avere un oggetto requisito di sicurezza e un oggetto definizioni di sicurezza nel documento OpenAPI affinché ESP convalida le rivendicazioni nel JWT firmato.

Per supportare l'autenticazione personalizzata:

OpenAPI 2.0

  1. Aggiungi quanto segue alla definizione di sicurezza nel documento OpenAPI: 
    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: []

OpenAPI 3.x

  1. Aggiungi quanto segue alla definizione di sicurezza nel documento OpenAPI: 
    components:
  securitySchemes:
    your_custom_auth_id:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: ""
          scopes: {}
      x-google-auth:
        issuer: "issuer of the token"
        jwksUri: "url to the public key"
        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 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 o audiences non è obbligatorio. ESP 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 x-google-audiences o audiences utilizzando valori separati da virgole. ESP accetta quindi i JWT con uno qualsiasi degli ID client specificati nell'attestazione aud.

ESP supporta due formati di chiave pubblica asimmetrica definiti dalle estensioni OpenAPI x-google-jwks_uri e jwksUri:

  • 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

    x-google-auth:
  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

    x-google-auth:
  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 o jwksUri sull'URI di un file che contiene la stringa della chiave codificata in base64url.

Se ometti x-google-jwks_uri o jwksUri, ESP seguirà il protocollo OpenID Connect Discovery per rilevare automaticamente l'URI JWKS per il provider OpenID specificato. ESP invierà una richiesta a x-google-issuer/.well-known/openid-configuration, analizzerà la risposta JSON e leggerà l'URI JWKS dal campo jwks_uri di primo livello.

Tieni presente che l'omissione di x-google-jwks_uri o jwksUri comporterà tempi di avvio a freddo più lunghi, in quanto l'ESP deve effettuare una chiamata remota aggiuntiva all'avvio. Pertanto, è consigliabile omettere questo campo solo se l'URI JWKS cambia spesso. La maggior parte dei provider OpenID certificati (come Google, Auth0 e Okta) ha URI JWKS stabili.

Puoi anche personalizzare le posizioni JWT aggiungendo estensioni x-google. Per maggiori dettagli, vedi Estensioni OpenAPI 2.0 o Estensioni OpenAPI 3.x.

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 <var>TOKEN</var>" "<var>ENDPOINTS_HOST</var>/echo"

Qui, sostituisci le variabili ENDPOINTS_HOST e TOKEN con il nome host API e il token di autenticazione, rispettivamente. Consulta Eseguire una richiesta autenticata a un'API Endpoints 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 "<var>ENDPOINTS_HOST</var>/echo?access_token=<var>TOKEN</var>"

Ricevere risultati autenticati nell'API

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

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

Passaggi successivi