Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Migrazione dell'identità delle app ai token ID OIDC

Quando un'app in esecuzione nel runtime Python 2 invia una richiesta a un'altra app App Engine, può utilizzare l'API App Engine App Identity per dichiarare 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à quando inviano 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 dell'utilizzo dei token ID OIDC per dichiarare e verificare l'identità:

Un'app App Engine denominata "App A" recupera un token ID da l'ambiente di Google Cloud runtime.
L'app A aggiunge questo token a un'intestazione della richiesta appena prima di inviare la richiesta all'app B, che è un'altra app 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 del account di servizio predefinito dell'app A.
L'app B confronta l'identità nel payload con un elenco di identità a cui è consentito rispondere. Se la richiesta proviene da un'app consentita, l'app B elabora la richiesta e risponde.

Procedura OAuth 2.0

Questa guida descrive come aggiornare le app App Engine per utilizzare OpenID Connect (OIDC) token ID per dichiarare l'identità e come aggiornare le altre app App Engine per utilizzare token ID per verificare l'identità prima di elaborare una richiesta.

Differenze principali tra le API App Identity e OIDC

Le app nel runtime Python 2 non devono dichiarare esplicitamente l'identità. Quando un'app utilizza le librerie Python httplib, urllib o urllib2 o il servizio di recupero URL di App Engine per inviare richieste in uscita, il runtime utilizza il servizio di recupero URL di App Engine per effettuare la richiesta. Se la richiesta viene inviata al dominio appspot.com, il recupero URL dichiara automaticamente l'identità dell'app richiedente aggiungendo l'intestazione X-Appengine-Inbound-Appid alla richiesta. Questa 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' Google Cloud ambiente di runtime 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 il account di servizio con cui è in esecuzione l'app, fornendo l'indirizzo email del account di servizio. Dovrai aggiungere del codice per estrarre il nome utente dal payload del token.

Se questo account di servizio è il service account App Engine predefinito a livello di app per il progetto, l'ID progetto è disponibile nell'indirizzo email del account di servizio account. La parte del nome utente dell'indirizzo è uguale all'ID progetto. In questo caso, il codice dell'app ricevente può cercarlo nell'elenco degli ID progetto da cui consentirà le richieste.

Tuttavia, se l'app richiedente sta utilizzando un service account gestito dall'utente anziché il service account App Engine predefinito, l'app ricevente può verificare solo l'identità di questo service account, che non definirà necessariamente l'ID progetto dell'app richiedente. In questo caso, l'app ricevente dovrà gestire un elenco di indirizzi email di account di servizio consentiti anziché un elenco di ID progetto consentiti.
Le quote per le chiamate all'API di recupero URL 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 Google Cloud schermata per il consenso OAuth della console. Né il recupero URL, né l'API App Identity, né le API OAuth 2.0 di Google comportano la fatturazione.

Panoramica del processo di migrazione

Per eseguire la migrazione delle app Python in modo che utilizzino le API OIDC per dichiarare e verificare l'identità:

Nelle app che devono dichiarare l'identità quando inviano richieste ad altre app App Engine:
1. 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 per l'esecuzione nel runtime Python 3.
2. Una volta che l'app è in esecuzione in Python 3, aggiornala in modo che richieda un token ID e aggiungilo a un'intestazione della richiesta.
Nelle app che devono verificare l'identità prima di elaborare una richiesta:
1. Inizia eseguendo 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 provenienti da app Python 2 che utilizzano l'API App Identity o da app Python 3 che utilizzano i token ID.
2. Una volta che le app Python 2 aggiornate sono stabili, esegui la migrazione al runtime Python 3. Continua a supportare sia i token ID sia le identità dell'API App Identity finché non sei certo che le app non debbano più supportare le richieste provenienti da app legacy.
3. Quando non devi più elaborare le richieste provenienti da app App Engine legacy, rimuovi il codice che verifica le identità dell'API App Identity.
Dopo aver testato le app, esegui il deployment dell'app che elabora le richieste per prima. Poi esegui il deployment dell'app Python 3 aggiornata che utilizza i token ID per dichiarare l'identità.

Dichiarare l'identità

Attendi che l'app sia in esecuzione in un ambiente Python 3, poi segui questi passaggi per eseguire l'upgrade dell'app in modo che dichiari l'identità con i token ID:

Installa la libreria client google-auth.
Aggiungi 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 una richiesta.
Testa gli aggiornamenti.

Installare la libreria client `google-auth` per le app Python 3

Per rendere disponibile la libreria client google-auth per la tua app Python 3, crea un file requirements.txt nella stessa cartella del file app.yaml e aggiungi la seguente riga:

     google-auth

Quando esegui il deployment dell'app, App Engine scarica tutte le dipendenze definite nel file requirements.txt.

Per lo sviluppo locale, ti consigliamo di installare le dipendenze in un ambiente virtuale come venv.

Aggiungere codice per dichiarare l'identità

Cerca nel codice tutte le istanze di invio di richieste ad altre app App Engine. Aggiorna queste istanze in modo che eseguano 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: passa l'oggetto richiesta che stai preparando per l'invio.
- audience: passa l'URL dell'app a cui stai inviando la richiesta. In questo modo, il token viene associato alla richiesta e non può essere utilizzato da un'altra app.
  
  Per chiarezza e specificità, ti consigliamo di passare 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 richiesta, imposta la seguente intestazione:
```
'Authorization': 'ID {}'.format(token)
```

Ad esempio:

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

from flask import Flask, render_template, request
from google.auth.transport import requests as reqs
from google.oauth2 import id_token
import requests

app = Flask(__name__)


@app.route("/", methods=["GET"])
def index():
    return render_template("index.html")


@app.route("/", methods=["POST"])
def make_request():
    url = request.form["url"]
    token = id_token.fetch_id_token(reqs.Request(), url)

    resp = requests.get(url, headers={"Authorization": f"Bearer {token}"})

    message = f"Response when calling {url}:\n\n"
    message += resp.text

    return message, 200, {"Content-type": "text/plain"}

Testare gli aggiornamenti per la dichiarazione dell'identità

Per eseguire l'app in locale e verificare se l'app può inviare correttamente i token ID:

Segui questi passaggi per rendere disponibili le credenziali del account di servizio App Engine predefinito nel tuo ambiente locale (le API OAuth di Google richiedono queste credenziali per generare un token ID):
1. Inserisci il seguente gcloud comando per recuperare la account di servizio account per l'account App Engine predefinito del tuo progetto:
  
  gcloud iam service-accounts keys create ~/key.json --iam-account project-ID@
  
  Sostituisci project-ID con l'ID del tuo Google Cloud progetto.
  
  Il file della chiave del account di servizio viene scaricato sul computer. Puoi spostare e rinominare questo file come preferisci. Assicurati di archiviare questo file in modo sicuro perché può essere utilizzato per l'autenticazione come service account. Se perdi il file o se il file è esposto a utenti non autorizzati users, elimina la account di servizio account e creane una nuova.
2. Inserisci questo comando:
```
<code>export GOOGLE_APPLICATION_CREDENTIALS=<var>service-account-key</var></code>
```
Sostituisci service-account-key con il percorso assoluto del file contenente la chiave del account di servizio che hai scaricato.
Nella stessa shell in cui hai esportato la GOOGLE_APPLICATION_CREDENTIALS variabile di ambiente, avvia l'app Python.
Invia una richiesta dall'app e verifica che vada a buon fine. Se non hai già un'app che può ricevere richieste e utilizzare i token ID per verificare le identità:
1. Scarica l'app di esempio "incoming".
2. Nel file main.py dell'esempio, aggiungi l'ID del tuo Google Cloud progetto a allowed_app_ids. Ad esempio:
```
 allowed_app_ids = [
    '<APP_ID_1>',
    '<APP_ID_2>',
    'my-project-id'
  ]
```
3. Esegui l'esempio aggiornato nel server di sviluppo locale Python 2 locale.

Verificare ed elaborare le richieste

Per eseguire l'upgrade delle app Python 2 in modo che utilizzino i token ID o le identità dell'API App Identity prima di elaborare le richieste:

Installa la libreria client google-auth.
Aggiorna il codice in modo che esegua le seguenti operazioni:
1. Se la richiesta contiene l'intestazione X-Appengine-Inbound-Appid, utilizza questa intestazione per verificare l'identità. Le app in esecuzione in un runtime legacy come Python 2 conterranno questa intestazione.
2. Se la richiesta non contiene l'intestazione X-Appengine-Inbound-Appid, controlla se è presente un token ID OIDC. Se il token esiste, verifica il payload del token e controlla l'identità del mittente.
Testa gli aggiornamenti.

Installare la libreria client google-auth per le app Python 2

Per rendere disponibile la libreria client google-auth per la tua app Python 2:

Crea un file requirements.txt nella stessa cartella del file app.yaml e aggiungi la seguente riga:
```
 google-auth==1.19.2
```
Ti consigliamo di utilizzare la versione 1.19.2 della libreria client Cloud Logging, poiché supporta le app Python 2.7.
Nel file app.yaml dell'app, specifica la libreria SSL nella sezione libraries se non è già specificata:
```
libraries:
- name: ssl
  version: latest
```
Crea una directory per archiviare le librerie di terze parti, ad esempio lib/. Poi utilizza pip 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 del file app.yaml. Aggiungi quanto segue al file appengine_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 cartella lib si trovi nella directory di lavoro corrente. Se non puoi garantire che lib si trovi sempre nella directory di lavoro corrente, specifica il percorso completo della cartella lib. Ad esempio:

import os
path = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'lib')

Per lo sviluppo locale, ti consigliamo di installare le dipendenze in un ambiente virtuale come virtualenv per Python 2.

Aggiornare il codice per la verifica delle richieste

Cerca nel codice tutte le istanze di recupero del valore dell'intestazione X-Appengine-Inbound-Appid. Aggiorna queste istanze in modo che eseguano le seguenti operazioni:

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'intestazione Authorization e recupera il relativo valore.

Il valore dell'intestazione è formattato come "ID: token".
Utilizza 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: passa il token estratto dalla richiesta in entrata.
- request: passa un nuovo oggetto google.auth.transport.Request.
- audience: passa l'URL dell'app corrente (l'app che invia la richiesta di verifica). Il server di autorizzazione di Google confronterà questo URL con l'URL fornito quando il token è stato generato originariamente. 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 e, incluso l'indirizzo email del 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 è uguale all'ID progetto dell'app che ha inviato la richiesta. Questo è lo stesso valore che è stato restituito in precedenza nell'intestazione X-Appengine-Inbound-Appid.
Se il nome utente/ID progetto è nell'elenco degli ID progetto consentiti, elabora la richiesta.

Ad esempio:

# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""
Authenticate requests coming from other App Engine instances.
"""

import logging

from google.auth.transport import requests
from google.oauth2 import id_token
import webapp2


def get_app_id(request):
    # Requests from App Engine Standard for Python 2.7 will include a
    # trustworthy X-Appengine-Inbound-Appid. Other requests won't have
    # that header, as the App Engine runtime will strip it out
    incoming_app_id = request.headers.get("X-Appengine-Inbound-Appid", None)
    if incoming_app_id is not None:
        return incoming_app_id

    # Other App Engine apps can get an ID token for the App Engine default
    # service account, which will identify the application ID. They will
    # have to include at token in an Authorization header to be recognized
    # by this method.
    auth_header = request.headers.get("Authorization", None)
    if auth_header is None:
        return None

    # The auth_header must be in the form Authorization: Bearer token.
    bearer, token = auth_header.split()
    if bearer.lower() != "bearer":
        return None

    try:
        info = id_token.verify_oauth2_token(token, requests.Request())
        service_account_email = info["email"]
        incoming_app_id, domain = service_account_email.split("@")
        if domain != "appspot.gserviceaccount.com":  # Not App Engine svc acct
            return None
        else:
            return incoming_app_id
    except Exception as e:
        # report or log if desired, as here:
        logging.warning("Request has bad OAuth2 id token: {}".format(e))
        return None


class MainPage(webapp2.RequestHandler):
    allowed_app_ids = ["other-app-id", "other-app-id-2"]

    def get(self):
        incoming_app_id = get_app_id(self.request)

        if incoming_app_id is None:
            self.abort(403)

        if incoming_app_id not in self.allowed_app_ids:
            self.abort(403)

        self.response.write("This is a protected page.")


app = webapp2.WSGIApplication([("/", MainPage)], debug=True)

Testare gli aggiornamenti per la verifica dell'identità

Per verificare che l'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 richieste da app Python 2 (che utilizzeranno l'API App Identity) e da app Python 3 che inviano token ID.

Se non hai aggiornato le app per inviare i token ID:

Scarica l' app di esempio "requesting".
Aggiungi le credenziali del account di servizio al tuo ambiente locale come descritto in Testare gli aggiornamenti per la dichiarazione 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 vada a buon fine.

Eseguire il deployment delle app

Quando sei pronto per eseguire il deployment delle app:

Testa le app su App Engine.
Se le app vengono eseguite senza errori, utilizza la suddivisione del traffico per aumentare gradualmente il traffico per le app aggiornate. Monitora attentamente le app per verificare la presenza di problemi prima di indirizzare più traffico alle app aggiornate.

Utilizzare un account di servizio diverso per dichiarare l'identità

Quando richiedi un token ID, la richiesta utilizza per impostazione predefinita l'identità del account di servizio App Engine predefinito. Quando verifichi il token, il payload del token contiene l'indirizzo email del service account predefinito, che esegue il mapping all'ID progetto dell'app.

Per impostazione predefinita, il service account App Engine predefinito ha un livello di autorizzazione molto elevato. Può visualizzare e modificare l'intero Google Cloud progetto, quindi nella maggior parte dei casi questo account non è appropriato da utilizzare quando l'app deve eseguire l'autenticazione con i servizi Cloud.

Tuttavia, il account di servizio predefinito è sicuro da utilizzare quando si dichiara l'identità dell'app, perché utilizzi il token ID solo per verificare l'identità dell'app che ha inviato una richiesta. Le autorizzazioni effettive concesse al account di servizio non vengono prese in considerazione o non sono necessarie durante questa procedura.

Se preferisci comunque utilizzare un account di servizio diverso per le richieste di token ID:

Imposta una variabile di ambiente denominata GOOGLE_APPLICATION_CREDENTIALS sul percorso di un file JSON contenente le credenziali del 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.

Migrazione dell'identità delle app ai token ID OIDC Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.