In questa pagina viene descritto come supportare l'autenticazione utente in Cloud Endpoints.
Per autenticare un utente, un'applicazione client deve inviare un JSON Web Token (JWT) nell'intestazione di autorizzazione del file HTTP all'API 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.
ESP convalida un JWT in modo efficace utilizzando il linguaggio le chiavi pubbliche dell'emittente. 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 il codice di autenticazione all'applicazione client, seguendo le istruzioni nella documentazione del provider di autenticazione.
-
Quando l'applicazione client invia una richiesta HTTP, l'intestazione di autorizzazione
la richiesta deve contenere le seguenti attestazioni JWT:
iss
(emittente)sub
(soggetto)aud
(pubblico)iat
(emissione:)exp
(data/ora di scadenza)
Configurare l'ESP per supportare l'autenticazione client
Devi disporre di un requisito e un oggetto definizioni nel documento OpenAPI affinché ESP le attestazioni nel JWT firmato.
Per supportare l'autenticazione personalizzata:
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"
Aggiungi una sezione di sicurezza a livello 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 le sezioni di sicurezza in a livello di API, mentre le impostazioni a livello di metodo hanno la precedenza Impostazioni 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
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
utilizzando valori separati da virgola. L'ESP accetta quindi i JWT con uno degli ID cliente specificati nel claim aud
.
ESP supporta due formati di chiavi pubbliche asimmetriche definiti
dall'x-google-jwks_uri
estensione OpenAPI:
-
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.
Se ometti x-google-jwks_uri
, ESP seguirà le
Scoperta OpenID Connect
per rilevare automaticamente l'URI JWKS del provider OpenID specificato.
ESP invierà una richiesta a x-google-issuer/.well-known/openid-configuration
,
analizzare la risposta JSON e leggere l'URI JWKS dal campo jwks_uri
di primo livello.
Tieni presente che l'omissione di x-google-jwks_uri
comporterà tempi di avvio a freddo più elevati, poiché
l'ESP deve effettuare un'altra chiamata remota all'avvio.
Di conseguenza, è 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 x-google-extensions
. Per maggiori dettagli, vedi estensioni openAPI.
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
. Per
esempio:
curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"
In questo caso, ENDPOINTS_HOST
e TOKEN
sono variabili di ambiente contenenti
rispettivamente nome host e token di autenticazione dell'API. Consulta:
Invio di una richiesta autenticata a un'API Endpoints.
per 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 "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"
Ricezione di risultati autenticati 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.
ESP invierà il risultato dell'autenticazione nell'X-Endpoint-API-UserInfo
all'API backend. Ti consigliamo di utilizzare questa intestazione anziché l'originale
Intestazione Authorization
. Questa intestazione è una stringa che base64url
codifica un oggetto JSON. Il formato degli oggetti 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