Questa pagina è stata tradotta dall'API Cloud Translation.

Migrazione dell'identità delle app ai token ID OIDC

Quando un'app in esecuzione nel runtime di Python 2 invia una richiesta a un'altra app App Engine, può utilizzare l'API App Identity di App Engine per affermare la propria identità. L'app che riceve la richiesta può utilizzare questa identità per determinare se deve elaborarla.

Se le tue applicazioni Python 3 devono affermare la propria identità quando inviano richieste ad altre applicazioni 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 affermare e verificare l'identità:

Un'app di App Engine denominata "App A" recupera un token ID da l'ambiente di runtime di Google Cloud.
L'app A aggiunge questo token a un'intestazione della 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. La 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 elabora la richiesta e risponde.

Processo OAuth 2.0

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

Differenze principali tra l'identità app e le API OIDC

Le app nel runtime Python 2 non devono dichiarare esplicitamente l'identità. Quando un'app utilizza le librerie Python httplib, urllib o urllib2 oppure Servizio di recupero URL di App Engine per inviare in uscita richieste, il runtime usa il servizio di recupero URL di App Engine per effettuare la richiesta. Se la richiesta viene inviato al dominio appspot.com, il recupero URL dichiara automaticamente l'identità dell'app richiedente aggiungendo X-Appengine-Inbound-Appid l'intestazione 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 l'intestazione della richiesta. Dovrai aggiornare tutto il codice che invia ad altre app App Engine in modo che le richieste contengano token ID.
L'intestazione X-Appengine-Inbound-Appid in una richiesta contiene l'ID progetto di all'app che ha inviato la richiesta.

Il payload del token ID OIDC di Google non identifica direttamente il progetto ID dell'app stessa. Il token identifica invece l'account di servizio in 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 tale account di servizio è il servizio App Engine predefinito a livello di app Google Cloud per il progetto, l'ID progetto sarà disponibile nell'indirizzo email dell'account di servizio. La parte del nome utente dell'indirizzo corrisponde all'ID progetto. In questo caso, il codice dell'app di ricezione può cercarlo nell'elenco degli ID progetto da cui consentirà le richieste.

Tuttavia, se l'app che ha inviato la richiesta utilizza un servizio gestito dall'utente Google Cloud dell'account di servizio predefinito di App Engine l'app ricevente potrà verificare solo l'identità di quel servizio , che non definirà necessariamente l'ID progetto dell'app richiedente. In questo caso, l'app di ricezione dovrà gestire un elenco di indirizzi email degli account di servizio consentiti anziché un elenco di ID progetto consentiti.
Le quote per le chiamate all'API URL Fetch sono diverse da quelle delle API OAuth 2.0 di Google per la concessione dei token. Puoi vedere il numero massimo di token che puoi concedere al giorno nella schermata per il consenso OAuth della console Google Cloud. Né il recupero URL, l'API App Identity, né le API OAuth 2.0 di Google sono soggette alla fatturazione.

Panoramica del processo di migrazione

Per eseguire la migrazione delle tue app Python per utilizzare le API OIDC per l'asserzione e la verifica dell'identità:

Nelle app che devono rivendicare l'identità durante l'invio di richieste ad altri App di App Engine:
1. Attendi che l'app sia in esecuzione in un ambiente Python 3 per eseguire la migrazione di token ID.
  
  Sebbene sia possibile utilizzare token ID nel runtime di Python 2, i passaggi in I Python 2 sono complessi e sono necessari solo temporaneamente fino a quando non aggiorni nel runtime Python 3.
2. Quando l'app è in esecuzione in Python 3, aggiorna l'app in richiedere un token ID e aggiungerlo 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 per supportare 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 App Identity API o app Python 3 che utilizzano token ID.
2. Una volta che le app Python 2 aggiornate sono stabili, eseguine la migrazione a Python 3 runtime. Continua a supportare sia i token ID sia le identità dell'API App Identity finché non avrai la certezza che le app non debbano più supportare le richieste da app legacy.
3. Quando non devi più elaborare le richieste della versione precedente di App Engine di Google Cloud, 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 in primo luogo. Poi esegui il deployment dell'app Python 3 aggiornata che utilizza i token ID per affermare l'identità.

Dichiarazione dell'identità

Attendi che l'app sia in esecuzione in un ambiente Python 3, quindi Per eseguire l'upgrade dell'app allo scopo di rivendicare l'identità con token ID, segui questi passaggi:

Installa la libreria client google-auth.
Aggiungi codice per richiedere un token ID dal token le API OAuth 2.0 e aggiungere il token a un'intestazione della richiesta prima di inviare una richiesta.
Verifica gli aggiornamenti.

Installazione della libreria client `google-auth` per le app Python 3

Per rendere la libreria client google-auth disponibile per l'app Python3, crea un file requirements.txt nella stessa cartella di app.yaml e aggiungi la riga seguente:

     google-auth

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

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

Aggiunta di codice per dichiarare l'identità

Cerca nel codice e trova tutte le istanze di invio di richieste ad altre app App Engine. Aggiorna queste istanze per eseguire le seguenti operazioni prima del giorno invia la richiesta:

Aggiungi le seguenti importazioni:

from google.auth.transport import requests as reqs
from google.oauth2 import id_token

Utilizza le funzionalità di 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 della richiesta che stai per inviare.
- audience: passa l'URL dell'app a cui stai inviando la richiesta. In questo modo il token viene associato alla richiesta e ne impedisce l'utilizzo da un'altra app.
  
  Per chiarezza e specificità, ti consigliamo di trasmettere il appspot.com URL creato da App Engine per il servizio specifico ricevono 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:

# 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"}

Test degli aggiornamenti per l'asserzione 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 dell'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 comando gcloud per recuperare il 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 il file come preferisci. Assicurati di archiviare questo file in modo sicuro perché può essere utilizzato per l'autenticazione come account di servizio. Se perdi il file o se è esposto a utenti non autorizzati, elimina la chiave dell'account di servizio 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 dell'account di servizio scaricata.
Nella stessa shell in cui hai esportato il file GOOGLE_APPLICATION_CREDENTIALS di variabile di ambiente, avvia l'app Python.
Invia una richiesta dall'app e conferma che ha esito positivo. Se non hai già un'app che può ricevere richieste e utilizzare token ID per verificare le identità:
1. Scarica l'esempio di feed "in arrivo" Google Cloud.
2. Nel file main.py del Sample, aggiungi l'ID del tuo progetto Google Cloud al allowed_app_ids. Ad esempio:
```
 allowed_app_ids = [
    '<APP_ID_1>',
    '<APP_ID_2>',
    'my-project-id'
  ]
```
3. Esegui l'esempio aggiornato in Python 2 server di sviluppo locale.

Verifica ed elaborazione delle richieste

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

Installa la libreria client google-auth.
Aggiorna il codice per eseguire le seguenti operazioni:
1. Se la richiesta contiene l'intestazione X-Appengine-Inbound-Appid, utilizzala per verificare l'identità. Le app in esecuzione in un runtime precedente come Python 2 conterranno questa intestazione.
2. Se la richiesta non contiene l'intestazione X-Appengine-Inbound-Appid, cerca un token ID OIDC. Se il token esiste, verifica il payload del token. e controllare l'identità del mittente.
Testa gli aggiornamenti.

Installazione della libreria client google-auth per le app Python 2

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

Crea un file requirements.txt nella stessa cartella di app.yaml e aggiungi la riga seguente:
```
 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 della tua app, specifica la libreria SSL nella sezione libraries se non è già stata specificata:
```
libraries:
- name: ssl
  version: latest
```
Crea una directory per archiviare le librerie di terze parti, ad esempio lib/. Quindi usa 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 tuo app.yaml file. Aggiungi quanto segue al tuo 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 l'elemento la cartella lib si trova nella directory di lavoro attuale. 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 come virtualenv per Python 2.

Aggiornamento del codice per la verifica delle richieste

Cerca nel codice e trova tutte le istanze di recupero del valore dell'X-Appengine-Inbound-Appid intestazione. Aggiorna queste istanze per eseguire 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 arrivo.
- 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 quello 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 diversi nomi/valori coppie, tra cui l'indirizzo email del l'account di servizio dell'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 è presente 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.
"""

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

import logging
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)

Aggiornamenti sui test per la verifica dell'identità

Per verificare che la tua app possa usare un token ID oppure l'intestazione X-Appengine-Inbound-Appid per verificare le richieste, eseguire l'app Python 2 server di sviluppo locale e inviare 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 token ID:

Scarica sample "richiesta" Google Cloud.
Aggiungi le credenziali dell'account di servizio all'ambiente locale come descritto in Eseguire il test degli aggiornamenti per l'asserzione delle app.
Utilizza i comandi standard di Python 3 per avviare l'app di esempio Python 3.
Invia una richiesta dall'app di esempio e verifica che vada a buon fine.

Deployment delle app

Quando tutto è pronto per il deployment delle app, devi:

Testa le app su in App Engine.
Se le app funzionano senza errori, utilizza la suddivisione del traffico per aumentare gradualmente il traffico per le app aggiornate. Monitora attentamente le app per rilevare eventuali problemi prima di indirizzare altro traffico alle app aggiornate.

Utilizzo di un account di servizio diverso per l'affermazione 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 del token contiene l'indirizzo email del servizio predefinito di Google Cloud, associato all'ID progetto della tua app.

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

Tuttavia, l'account di servizio predefinito è sicuro da utilizzare per affermare 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 all'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 di abilitazione, procedi nel seguente modo:

Imposta una variabile di ambiente denominata GOOGLE_APPLICATION_CREDENTIALS sul percorso di un file JSON contenente le credenziali dell'account di servizio. Consulta le nostre consigli per archiviare in sicurezza queste credenziali.
Utilizza google.oauth2.id_token.fetch_id_token(request, audience) per recuperare un token ID.
Quando verifichi questo token, il relativo payload conterrà l'indirizzo email del nuovo account di servizio.