Quando un'app in esecuzione nel runtime Python 2 invia una richiesta a un'altra app di App Engine, può utilizzare l'API App Identity di App Engine per rivendicare la propria identità. L'app che riceve la richiesta può utilizzare questa identità per determinare se deve elaborare la richiesta.
Se le tue app Python 3 devono dichiarare la propria identità durante l'invio di richieste ad altre app App Engine, puoi utilizzare i token ID OpenID Connect (OIDC) emessi e decodificati dalle API OAuth 2.0 di Google.
Ecco una panoramica sull'utilizzo dei token ID OIDC per l'asserzione e la verifica dell'identità:
- Un'app App Engine denominata "App A" recupera un token ID dall'ambiente di runtime di Google Cloud.
- L'app A aggiunge questo token all'intestazione di una richiesta poco prima di inviare la richiesta all'app B, che è un'altra app di App Engine.
- L'app B utilizza le API OAuth 2.0 di Google per verificare il payload del token. Il payload decodificato contiene l'identità verificata dell'app A sotto forma di indirizzo email dell'account di servizio predefinito dell'app A.
- L'app B confronta l'identità nel payload con un elenco di identità a cui è autorizzata a rispondere. Se la richiesta proviene da un'app consentita, l'app B la elabora e risponde.
Questa guida descrive come aggiornare le app App Engine in modo da utilizzare i token ID OpenID Connect (OIDC) per l'asserzione dell'identità e aggiornare le altre app App Engine in modo da utilizzare i token ID per verificare l'identità prima di elaborare una richiesta.
Differenze principali tra le API App Identity e OIDC
Per le app nel runtime Python 2 non è necessario dichiarare esplicitamente l'identità. Quando un'app utilizza le librerie Python
httplib
,urllib
ourllib2
o il servizio di recupero URL di App Engine per inviare le richieste in uscita, il runtime utilizza il servizio di recupero URL di App Engine per effettuare la richiesta. Se la richiesta viene inviata al dominioappspot.com
, lo strumento Recupero URL dichiara automaticamente l'identità dell'app richiedente aggiungendo l'intestazioneX-Appengine-Inbound-Appid
alla richiesta. L'intestazione contiene l'ID applicazione dell'app (chiamato anche ID progetto).Le app nel runtime Python 3 devono dichiarare esplicitamente l'identità recuperando un token ID OIDC dall'ambiente di runtime di Google Cloud e aggiungendolo all'intestazione della richiesta. Dovrai aggiornare tutto il codice che invia richieste ad altre app App Engine in modo che le richieste contengano un token ID OIDC.
L'intestazione
X-Appengine-Inbound-Appid
in una richiesta contiene l'ID progetto dell'app che ha inviato la richiesta.Il payload del token ID OIDC di Google non identifica direttamente l'ID progetto dell'app stessa. Il token identifica invece l'account di servizio su cui viene eseguita l'app, fornendo l'indirizzo email dell'account di servizio. Dovrai aggiungere del codice per estrarre il nome utente dal payload del token.
Se questo account di servizio è l'account di servizio App Engine predefinito a livello di app per il progetto, l'ID progetto si trova nell'indirizzo email dell'account di servizio. La parte del nome utente dell'indirizzo è uguale all'ID progetto. In questo caso, il codice dell'app di destinazione può cercarlo nell'elenco degli ID progetto da cui consentirà le richieste.
Tuttavia, se l'app richiedente utilizza un account di servizio gestito dall'utente anziché l'account di servizio App Engine predefinito, l'app ricevente può verificare solo l'identità di quell'account di servizio, il che non definirà necessariamente l'ID progetto dell'app richiedente. In questo caso, l'app ricevente dovrà gestire un elenco di indirizzi email degli account di servizio consentiti anziché un elenco di ID progetto consentiti.
Le quote per le chiamate API URL Fetch sono diverse dalle quote delle API OAuth 2.0 di Google per la concessione dei token. Puoi visualizzare il numero massimo di token che puoi concedere al giorno nella schermata per il consenso OAuth della console Google Cloud. Non sono previsti addebiti né per il recupero URL, né l'API App Identity né le API OAuth 2.0 di Google.
Panoramica del processo di migrazione
Per eseguire la migrazione delle tue app Python in modo da utilizzare le API OIDC per l'asserzione e la verifica dell'identità:
Nelle app che devono dichiarare l'identità durante l'invio di richieste ad altre app App Engine:
Attendi che l'app sia in esecuzione in un ambiente Python 3 per eseguire la migrazione ai token ID.
Sebbene sia possibile utilizzare i token ID nel runtime Python 2, i passaggi in Python 2 sono complessi e sono necessari solo temporaneamente finché non aggiorni l'app in modo che venga eseguita nel runtime Python 3.
Una volta che l'app è in esecuzione in Python 3, aggiornala per richiedere un token ID e aggiungi il token a un'intestazione della richiesta.
Nelle app che devono verificare l'identità prima di elaborare una richiesta:
Per iniziare, esegui l'upgrade delle app Python 2 in modo che supportino sia i token ID sia le identità dell'API App Identity. In questo modo le tue app potranno verificare ed elaborare le richieste dalle app Python 2 che utilizzano l'API App Identity o dalle app Python 3 che utilizzano i token ID.
Una volta stabili le app Python 2 di cui è stato eseguito l'upgrade, eseguine la migrazione al runtime Python 3. Continua a supportare sia i token ID sia le identità dell'API App Identity fino a quando non sei sicuro che le app non debbano più supportare le richieste provenienti dalle app legacy.
Quando non devi più elaborare le richieste dalle app legacy di App Engine, rimuovi il codice che verifica le identità dell'API App Identity.
Dopo aver testato le tue app, deploy dell'app che elabora le richieste. Quindi, esegui il deployment dell'app Python 3 aggiornata che utilizza i token ID per l'asserzione dell'identità.
Rivendicazione dell'identità
Attendi che l'app sia in esecuzione in un ambiente Python 3, quindi segui questi passaggi per eseguire l'upgrade dell'app e rivendicare l'identità con token ID:
Installa la libreria client
google-auth
.Aggiungi il codice per richiedere un token ID dalle API OAuth 2.0 di Google e aggiungi il token a un'intestazione della richiesta prima di inviare la richiesta.
Testa gli aggiornamenti.
Installazione della libreria client google-auth
per le app Python 3
Per rendere disponibile la libreria client google-auth
alla tua app Python3, crea un file requirements.txt
nella stessa cartella del file app.yaml
e aggiungi la riga seguente:
google-auth
Quando esegui il deployment dell'app, App Engine scarica tutte le dipendenze definite nel file requirements.txt
.
Per lo sviluppo locale, consigliamo di installare le dipendenze in un ambiente virtuale come venv.
Aggiunta di codice per l'asserzione dell'identità
Cerca nel codice e trova tutte le istanze di invio di richieste ad altre app di App Engine. Aggiorna le istanze in modo da eseguire le seguenti operazioni prima di inviare la richiesta:
Aggiungi le seguenti importazioni:
from google.auth.transport import requests as reqs from google.oauth2 import id_token
Utilizza
google.oauth2.id_token.fetch_id_token(request, audience)
per recuperare un token ID. Includi i seguenti parametri nella chiamata al metodo:request
: trasmetti l'oggetto della richiesta che stai per inviare.audience
: trasmetti l'URL dell'app a cui stai inviando la richiesta. Questo associa il token alla richiesta e ne impedisce l'utilizzo da parte di un'altra app.Per chiarezza e specificità, ti consigliamo di trasmettere l'URL
appspot.com
creato da App Engine per il servizio specifico che riceve la richiesta, anche se utilizzi un dominio personalizzato per l'app.
Nell'oggetto della richiesta, imposta la seguente intestazione:
'Authorization': 'ID {}'.format(token)
Ad esempio:
Test degli aggiornamenti per l'affermazione dell'identità
Per eseguire la tua app in locale e verificare se può inviare correttamente i token ID:
Segui questi passaggi per rendere disponibili nel tuo ambiente locale le credenziali dell'account di servizio App Engine predefinito (le API OAuth di Google richiedono queste credenziali per generare un token ID):
Inserisci il seguente comando
gcloud
per recuperare la chiave dell'account di servizio per l'account App Engine predefinito del tuo progetto:gcloud iam service-accounts keys create ~/key.json --iam-account project-ID@appspot.gserviceaccount.com
Sostituisci project-ID con l'ID del tuo progetto Google Cloud.
Il file della chiave dell'account di servizio viene scaricato sul computer. Puoi spostare e rinominare questo file come preferisci. Assicurati di archiviare questo file in modo sicuro, poiché può essere utilizzato per autenticarsi come account di servizio. Se perdi il file o se il file è esposto a utenti non autorizzati, elimina la chiave dell'account di servizio e creane una nuova.
Inserisci questo comando:
<code>export GOOGLE_APPLICATION_CREDENTIALS=<var>service-account-key</var></code>
Sostituisci service-account-key con il nome di percorso assoluto del file che contiene la chiave dell'account di servizio che hai scaricato.
Nella stessa shell in cui hai esportato la variabile di ambiente
GOOGLE_APPLICATION_CREDENTIALS
, avvia l'app Python.Invia una richiesta dall'app e verifica che l'operazione vada a buon fine. Se non hai già un'app in grado di ricevere richieste e utilizzare token ID per verificare le identità:
- Scarica l'app di esempio "in arrivo".
Nel file
main.py
dell'esempio, aggiungi l'ID del tuo progetto Google Cloud aallowed_app_ids
. Ad esempio:allowed_app_ids = [ '<APP_ID_1>', '<APP_ID_2>', 'my-project-id' ]
Esegui l'esempio aggiornato nel server di sviluppo locale Python 2.
Verifica ed elaborazione delle richieste
Per eseguire l'upgrade delle tue app Python 2 in modo da utilizzare i token ID o le identità dell'API App Identity prima di elaborare le richieste:
Installa la libreria client google-auth.
Aggiorna il codice per:
Se la richiesta contiene l'intestazione
X-Appengine-Inbound-Appid
, utilizzala per verificare l'identità. Le app in esecuzione in un runtime legacy come Python 2 conterranno questa intestazione.Se la richiesta non contiene l'intestazione
X-Appengine-Inbound-Appid
, verifica se è presente un token ID OIDC. Se il token esiste, verifica il payload del token e controlla l'identità del mittente.
Testa gli aggiornamenti.
Installazione della libreria client google-auth per le app Python 2
Per rendere disponibile la libreria client google-auth
alla tua app Python 2:
Crea un file
requirements.txt
nella stessa cartella del fileapp.yaml
e aggiungi la seguente riga:google-auth==1.19.2
Ti consigliamo di utilizzare la versione 1.19.2 della libreria client di Cloud Logging poiché supporta le app Python 2.7.
Nel file
app.yaml
dell'app, specifica la libreria SSL nella sezionelibraries
, se non è già specificata:libraries: - name: ssl version: latest
Crea una directory per archiviare le librerie di terze parti, ad esempio
lib/
. Usa quindipip install
per installare le librerie nella directory. Ad esempio:pip install -t lib -r requirements.txt
Crea un file
appengine_config.py
nella stessa cartella in cui si trova il fileapp.yaml
. Aggiungi il seguente codice al tuo fileappengine_config.py
:# appengine_config.py import pkg_resources from google.appengine.ext import vendor # Set path to your libraries folder. path = 'lib' # Add libraries installed in the path folder. vendor.add(path) # Add libraries to pkg_resources working set to find the distribution. pkg_resources.working_set.add_entry(path)
Il file
appengine_config.py
nell'esempio precedente presuppone che la cartellalib
si trovi nella directory di lavoro corrente. Se non puoi garantire chelib
si trovi sempre nella directory di lavoro attuale, specifica il percorso completo della cartellalib
. Ad esempio:import os path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')
Per lo sviluppo locale, consigliamo di installare le dipendenze in un ambiente virtuale come virtualenv per Python 2.
Aggiornamento del codice per la verifica delle richieste
Cerca nel codice e trova tutte le istanze in cui viene recuperato il valore dell'intestazione X-Appengine-Inbound-Appid
. Aggiorna queste istanze per:
Aggiungi le seguenti importazioni:
from google.auth.transport import requests as reqs from google.oauth2 import id_token
Se la richiesta in entrata non contiene l'intestazione
X-Appengine-Inbound-Appid
, cerca l'intestazioneAuthorization
e recupera il relativo valore.Il valore dell'intestazione è formattato come "ID: token".
Utilizzare
google.oauth2.id_token.verify_oauth2_token(token, request, audience)
per verificare e recuperare il payload del token decodificato. Includi i seguenti parametri nella chiamata al metodo:token
: trasmetti il token estratto dalla richiesta in entrata.request
: trasmetti un nuovo oggettogoogle.auth.transport.Request
.audience
: trasmetti l'URL dell'app corrente (quella che invia la richiesta di verifica). Il server di autorizzazione di Google confronterà questo URL con l'URL fornito al momento della generazione originale del token. Se gli URL non corrispondono, il token non verrà verificato e il server di autorizzazione restituirà un errore.
Il metodo
verify_oauth2_token
restituisce il payload del token decodificato, che contiene diverse coppie nome/valore, tra cui l'indirizzo email dell'account di servizio predefinito per l'app che ha generato il token.Estrai il nome utente dall'indirizzo email nel payload del token.
Il nome utente corrisponde all'ID progetto dell'app che ha inviato la richiesta. Si tratta dello stesso valore restituito in precedenza nell'intestazione
X-Appengine-Inbound-Appid
.Se il nome utente/l'ID progetto è incluso nell'elenco degli ID progetto consentiti, elabora la richiesta.
Ad esempio:
Test degli aggiornamenti per la verifica dell'identità
Per testare che la tua app possa utilizzare un token ID o l'intestazione X-Appengine-Inbound-Appid
per verificare le richieste, esegui l'app nel server di sviluppo locale Python 2 e invia le richieste dalle app Python 2 (che utilizzeranno l'API App Identity) e dalle app Python 3 che inviano token ID.
Se non hai aggiornato le tue app per inviare i token ID:
Scarica l'app di esempio "richiesta".
Aggiungi le credenziali dell'account di servizio al tuo ambiente locale come descritto nella sezione Test degli aggiornamenti per l'asserzione delle app.
Utilizza i comandi Python 3 standard per avviare l'app di esempio Python 3.
Invia una richiesta dall'app di esempio e verifica che l'operazione vada a buon fine.
Deployment delle app
Quando è tutto pronto per eseguire il deployment delle tue app, devi:
Se le app vengono eseguite senza errori, utilizza la suddivisione del traffico per aumentare lentamente il traffico per le app aggiornate. Monitora attentamente le app per rilevare eventuali problemi prima di indirizzare più traffico alle app aggiornate.
Utilizzo di un account di servizio diverso per l'asserzione dell'identità
Quando richiedi un token ID, per impostazione predefinita la richiesta utilizza l'identità dell'account di servizio predefinito di App Engine. Quando verifichi il token, il payload contiene l'indirizzo email dell'account di servizio predefinito, che è mappato all'ID progetto della tua app.
L'account di servizio predefinito di App Engine ha un livello molto elevato di autorizzazioni per impostazione predefinita. Può visualizzare e modificare l'intero progetto Google Cloud, quindi nella maggior parte dei casi questo account non è appropriato da usare quando la tua app deve essere autenticata con i servizi Cloud.
Tuttavia, l'account di servizio predefinito può essere utilizzato in sicurezza quando si assegne l'identità dell'app perché si utilizza solo il token ID per verificare l'identità dell'app che ha inviato una richiesta. Le autorizzazioni effettive concesse all'account di servizio non sono considerate né necessarie durante questo processo.
Se preferisci comunque utilizzare un account di servizio diverso per le richieste del token ID:
Imposta una variabile di ambiente denominata
GOOGLE_APPLICATION_CREDENTIALS
sul percorso di un file JSON contenente le credenziali dell'account di servizio. Consulta i nostri consigli per archiviare in modo sicuro queste credenziali.Utilizza
google.oauth2.id_token.fetch_id_token(request, audience)
per recuperare un token ID.Quando verifichi questo token, il payload del token conterrà l'indirizzo email del nuovo account di servizio.