Tutorial sull'autenticazione degli utenti finali per Cloud Run

Questo tutorial mostra come creare un servizio di voto composto da:

  • Un client basato su browser che:

    1. Utilizza Identity Platform per recuperare un token ID.
    2. Consente agli utenti di votare il proprio animale domestico preferito.
    3. Aggiunge questo token ID a una richiesta al server Cloud Run che elabora il voto.

  • Un server Cloud Run che:

    1. Controlla che l'utente finale abbia eseguito l'autenticazione correttamente fornendo un token ID valido.
    2. Elabora il voto dell'utente finale.
    3. Utilizzando le proprie credenziali, invia il voto a Cloud SQL per l'archiviazione.

  • Un database PostgreSQL che archivia i voti.

Per semplicità, questo tutorial utilizza Google come provider: gli utenti devono autenticarsi utilizzando un Account Google per ottenere il token ID. Tuttavia, puoi utilizzare altri provider o metodi di autenticazione per consentire l'accesso agli utenti.

Questo servizio riduce al minimo i rischi per la sicurezza utilizzando Secret Manager per proteggere i dati sensibili utilizzati per connettersi all'istanza Cloud SQL. Utilizza anche un'identità di servizio con privilegi minimi per proteggere l'accesso al database.

Configurazione dei valori predefiniti di gcloud

Per configurare gcloud con i valori predefiniti per il tuo servizio Cloud Run:

  1. Imposta il progetto predefinito:

    gcloud config set project PROJECT_ID

    Sostituisci PROJECT_ID con il nome del progetto che hai creato per questo tutorial.

  2. Configura gcloud per la regione scelta:

    gcloud config set run/region REGION

    Sostituisci REGION con la regione Cloud Run supportata che preferisci.

Località Cloud Run

Cloud Run è regionale, il che significa che l'infrastruttura che esegue i tuoi servizi Cloud Run si trova in una regione specifica ed è gestita da Google per essere disponibile in modo ridondante in tutte le zone all'interno di quella regione.

Il rispetto dei requisiti di latenza, disponibilità o durabilità sono fattori primari per la selezione della regione in cui vengono eseguiti i servizi Cloud Run. In genere puoi selezionare la regione più vicina ai tuoi utenti, ma devi considerare la posizione degli altri Google Cloud prodotti utilizzati dal tuo servizio Cloud Run. L'utilizzo combinato dei prodotti Google Cloud in più località può influire sulla latenza e sui costi del servizio.

Cloud Run è disponibile nelle seguenti regioni:

Soggetto ai prezzi di Livello 1

Soggetto ai prezzi di Livello 2

  • africa-south1 (Johannesburg)
  • asia-east2 (Hong Kong)
  • asia-northeast3 (Seul, Corea del Sud)
  • asia-southeast1 (Singapore)
  • asia-southeast2 (Giacarta)
  • asia-south2 (Delhi, India)
  • australia-southeast1 (Sydney)
  • australia-southeast2 (Melbourne)
  • europe-central2 (Varsavia, Polonia)
  • europe-west10 (Berlino)
  • europe-west12 (Torino)
  • europe-west2 (Londra, Regno Unito) icona foglia Bassi livelli di CO2
  • europe-west3 (Francoforte, Germania)
  • europe-west6 (Zurigo, Svizzera) icona foglia A basse emissioni di CO2
  • me-central1 (Doha)
  • me-central2 (Dammam)
  • northamerica-northeast1 (Montreal) icona foglia Bassi livelli di CO2
  • northamerica-northeast2 (Toronto) icona foglia Bassi livelli di CO2
  • southamerica-east1 (San Paolo, Brasile) icona foglia Bassi livelli di CO2
  • southamerica-west1 (Santiago, Cile) icona foglia Bassi livelli di CO2
  • us-west2 (Los Angeles)
  • us-west3 (Salt Lake City)
  • us-west4 (Las Vegas)

Se hai già creato un servizio Cloud Run, puoi visualizzare la regione nella dashboard Cloud Run nella consoleGoogle Cloud .

Recupero dell'esempio di codice

Per recuperare l'esempio di codice da utilizzare:

  1. Clona il repository dell'app di esempio sulla tua macchina locale:

    Node.js 

    git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

    In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

    Python 

    git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

    In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

    Java 

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    In alternativa, puoi scaricare il campione come file ZIP ed estrarlo.

  2. Passa alla directory che contiene il codice campione di Cloud Run:

    Node.js 

    cd nodejs-docs-samples/run/idp-sql/

    Python 

    cd python-docs-samples/run/idp-sql/

    Java 

    cd java-docs-samples/run/idp-sql/

Visualizzazione dell'architettura

Diagramma dell'architettura
Il diagramma mostra un utente finale che esegue l'accesso tramite una finestra di dialogo di accesso Google fornita da Identity Platform e che viene reindirizzato a Cloud Run con l'identità dell'utente.

  1. Un utente finale invia la prima richiesta al server Cloud Run.

  2. Il client viene caricato nel browser.

  3. L'utente fornisce le credenziali di accesso tramite la finestra di dialogo di accesso Google di Identity Platform. Un avviso dà il benvenuto all'utente che ha eseguito l'accesso.

  4. Il controllo viene reindirizzato al server. L'utente finale vota utilizzando il client, che recupera un token ID da Identity Platform e lo aggiunge all'intestazione della richiesta di voto.

  5. Quando il server riceve la richiesta, verifica il token ID di Identity Platform, confermando che l'utente finale è autenticato correttamente. Il server invia il voto a Cloud SQL utilizzando le proprie credenziali.

Comprendere il codice principale

Il campione è implementato come client e server, come descritto di seguito.

Integrazione con Identity Platform: codice lato client

Questo esempio utilizza gli SDK Firebase per l'integrazione con Identity Platform al fine di accedere e gestire gli utenti. Per connettersi a Identity Platform, JavaScript lato client contiene il riferimento alle credenziali del progetto come oggetto di configurazione e importa gli SDK Firebase JavaScript necessari:

const config = {
  apiKey: 'API_KEY',
  authDomain: 'PROJECT_ID.firebaseapp.com',
};
 
<!-- Firebase App (the core Firebase SDK) is always required and must be listed first-->
<script src="https://www.gstatic.com/firebasejs/7.18/firebase-app.js"></script>
<!-- Add Firebase Auth service-->
<script src="https://www.gstatic.com/firebasejs/7.18/firebase-auth.js"></script>

L'SDK Firebase JavaScript gestisce il flusso di accesso chiedendo all'utente finale di accedere al proprio Account Google tramite una finestra popup. e li reindirizza al servizio.

function signIn() {
  const provider = new firebase.auth.GoogleAuthProvider();
  provider.addScope('https://www.googleapis.com/auth/userinfo.email');
  firebase
    .auth()
    .signInWithPopup(provider)
    .then(result => {
      // Returns the signed in user along with the provider's credential
      console.log(`${result.user.displayName} logged in.`);
      window.alert(`Welcome ${result.user.displayName}!`);
    })
    .catch(err => {
      console.log(`Error during sign in: ${err.message}`);
      window.alert('Sign in failed. Retry or check your browser logs.');
    });
}

Quando un utente accede correttamente, il client utilizza i metodi Firebase per generare un token ID. Il client aggiunge il token ID all'intestazione Authorization della richiesta al server.

async function vote(team) {
  if (firebase.auth().currentUser) {
    // Retrieve JWT to identify the user to the Identity Platform service.
    // Returns the current token if it has not expired. Otherwise, this will
    // refresh the token and return a new one.
    try {
      const token = await firebase.auth().currentUser.getIdToken();
      const response = await fetch('/', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          Authorization: `Bearer ${token}`,
        },
        body: 'team=' + team, // send application data (vote)
      });
      if (response.ok) {
        const text = await response.text();
        window.alert(text);
        window.location.reload();
      }
    } catch (err) {
      console.log(`Error when submitting vote: ${err}`);
      window.alert('Something went wrong... Please try again!');
    }
  } else {
    window.alert('User not signed in.');
  }
}

Integrazione con Identity Platform: codice lato server

Il server utilizza l'SDK Firebase Admin per verificare il token ID utente inviato dal client. Se il token ID fornito ha il formato corretto, non è scaduto ed è firmato correttamente, il metodo restituisce il token ID decodificato. Il server estrae l'uid di Identity Platform per l'utente.

Node.js 

const firebase = require('firebase-admin');
// Initialize Firebase Admin SDK
firebase.initializeApp();

// Extract and verify Id Token from header
const authenticateJWT = (req, res, next) => {
  const authHeader = req.headers.authorization;
  if (authHeader) {
    const token = authHeader.split(' ')[1];
    // If the provided ID token has the correct format, is not expired, and is
    // properly signed, the method returns the decoded ID token
    firebase
      .auth()
      .verifyIdToken(token)
      .then(decodedToken => {
        const uid = decodedToken.uid;
        req.uid = uid;
        next();
      })
      .catch(err => {
        req.logger.error(`Error with authentication: ${err}`);
        return res.sendStatus(403);
      });
  } else {
    return res.sendStatus(401);
  }
};

Python 

def jwt_authenticated(func: Callable[..., int]) -> Callable[..., int]:
    """Use the Firebase Admin SDK to parse Authorization header to verify the
    user ID token.

    The server extracts the Identity Platform uid for that user.
    """

    @wraps(func)
    def decorated_function(*args: a, **kwargs: a) -> a:
        header = request.headers.get("Authorization", None)
        if header:
            token = header.split(" ")[1]
            try:
                decoded_token = firebase_admin.auth.verify_id_token(token)
            except Exception as e:
                logger.exception(e)
                return Response(status=403, response=f"Error with authentication: {e}")
        else:
            return Response(status=401)

        request.uid = decoded_token["uid"]
        return func(*args, **kwargs)

    return decorated_function

Java 

/** Extract and verify Id Token from header */
private String authenticateJwt(Map<String, String> headers) {
  String authHeader =
      (headers.get("authorization") != null)
          ? headers.get("authorization")
          : headers.get("Authorization");
  if (authHeader != null) {
    String idToken = authHeader.split(" ")[1];
    // If the provided ID token has the correct format, is not expired, and is
    // properly signed, the method returns the decoded ID token
    try {
      FirebaseToken decodedToken = FirebaseAuth.getInstance().verifyIdToken(idToken);
      String uid = decodedToken.getUid();
      return uid;
    } catch (FirebaseAuthException e) {
      logger.error("Error with authentication: " + e.toString());
      throw new ResponseStatusException(HttpStatus.FORBIDDEN, "", e);
    }
  } else {
    logger.error("Error no authorization header");
    throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
  }
}

Connessione del server a Cloud SQL

Il server si connette al socket di dominio Unix dell'istanza Cloud SQL utilizzando il formato: /cloudsql/CLOUD_SQL_CONNECTION_NAME.

Node.js 

/**
 * Connect to the Cloud SQL instance through UNIX Sockets
 *
 * @param {object} credConfig The Cloud SQL connection configuration from Secret Manager
 * @returns {object} Knex's PostgreSQL client
 */
const connectWithUnixSockets = async credConfig => {
  const dbSocketPath = process.env.DB_SOCKET_PATH || '/cloudsql';
  // Establish a connection to the database
  return Knex({
    client: 'pg',
    connection: {
      user: credConfig.DB_USER, // e.g. 'my-user'
      password: credConfig.DB_PASSWORD, // e.g. 'my-user-password'
      database: credConfig.DB_NAME, // e.g. 'my-database'
      host: `${dbSocketPath}/${credConfig.CLOUD_SQL_CONNECTION_NAME}`,
    },
    ...config,
  });
};

Python 

def init_unix_connection_engine(
    db_config: dict[str, int]
) -> sqlalchemy.engine.base.Engine:
    """Initializes a Unix socket connection pool for a Cloud SQL instance of PostgreSQL.

    Args:
        db_config: a dictionary with connection pool config

    Returns:
        A SQLAlchemy Engine instance.
    """
    creds = credentials.get_cred_config()
    db_user = creds["DB_USER"]
    db_pass = creds["DB_PASSWORD"]
    db_name = creds["DB_NAME"]
    db_socket_dir = creds.get("DB_SOCKET_DIR", "/cloudsql")
    cloud_sql_connection_name = creds["CLOUD_SQL_CONNECTION_NAME"]

    pool = sqlalchemy.create_engine(
        # Equivalent URL:
        # postgres+pg8000://<db_user>:<db_pass>@/<db_name>
        #                         ?unix_sock=<socket_path>/<cloud_sql_instance_name>/.s.PGSQL.5432
        sqlalchemy.engine.url.URL.create(
            drivername="postgresql+pg8000",
            username=db_user,  # e.g. "my-database-user"
            password=db_pass,  # e.g. "my-database-password"
            database=db_name,  # e.g. "my-database-name"
            query={
                "unix_sock": f"{db_socket_dir}/{cloud_sql_connection_name}/.s.PGSQL.5432"
                # e.g. "/cloudsql", "<PROJECT-NAME>:<INSTANCE-REGION>:<INSTANCE-NAME>"
            },
        ),
        **db_config,
    )
    pool.dialect.description_encoding = None
    logger.info("Database engine initialized from unix connection")

    return pool

Java

Utilizza l'integrazione Spring Cloud Google Cloud PostgreSQL starter per interagire con i tuoi database PostgreSQL in Cloud SQL utilizzando le librerie Spring JDBC. Imposta la configurazione di Cloud SQL per MySQL in modo che configuri automaticamente un bean DataSource che, insieme a Spring JDBC, fornisce un bean oggetto JdbcTemplate che consente operazioni come l'interrogazione e la modifica di un database.

# Uncomment and add env vars for local development
# spring.datasource.username=${DB_USER}
# spring.datasource.password=${DB_PASSWORD}
# spring.cloud.gcp.sql.database-name=${DB_NAME}
# spring.cloud.gcp.sql.instance-connection-name=${CLOUD_SQL_CONNECTION_NAME}  
private final JdbcTemplate jdbcTemplate;

public VoteController(JdbcTemplate jdbcTemplate) {
  this.jdbcTemplate = jdbcTemplate;
}

Gestione della configurazione sensibile con Secret Manager

Secret Manager fornisce un archivio centralizzato e sicuro di dati sensibili come la configurazione di Cloud SQL. Il server inserisce le credenziali Cloud SQL da Secret Manager in fase di runtime tramite una variabile di ambiente. Scopri di più sull'utilizzo dei secret con Cloud Run.

Node.js 

// CLOUD_SQL_CREDENTIALS_SECRET is the resource ID of the secret, passed in by environment variable.
// Format: projects/PROJECT_ID/secrets/SECRET_ID/versions/VERSION
const {CLOUD_SQL_CREDENTIALS_SECRET} = process.env;
if (CLOUD_SQL_CREDENTIALS_SECRET) {
  try {
    // Parse the secret that has been added as a JSON string
    // to retrieve database credentials
    return JSON.parse(CLOUD_SQL_CREDENTIALS_SECRET.toString('utf8'));
  } catch (err) {
    throw Error(
      `Unable to parse secret from Secret Manager. Make sure that the secret is JSON formatted: ${err}`
    );
  }
}

Python 

def get_cred_config() -> dict[str, str]:
    """Retrieve Cloud SQL credentials stored in Secret Manager
    or default to environment variables.

    Returns:
        A dictionary with Cloud SQL credential values
    """
    secret = os.environ.get("CLOUD_SQL_CREDENTIALS_SECRET")
    if secret:
        return json.loads(secret)

Java 

/** Retrieve config from Secret Manager */
public static HashMap<String, Object> getConfig() {
  String secret = System.getenv("CLOUD_SQL_CREDENTIALS_SECRET");
  if (secret == null) {
    throw new IllegalStateException("\"CLOUD_SQL_CREDENTIALS_SECRET\" is required.");
  }
  try {
    HashMap<String, Object> config = new Gson().fromJson(secret, HashMap.class);
    return config;
  } catch (JsonSyntaxException e) {
    logger.error(
        "Unable to parse secret from Secret Manager. Make sure that it is JSON formatted: "
            + e);
    throw new RuntimeException(
        "Unable to parse secret from Secret Manager. Make sure that it is JSON formatted.");
  }
}

Configura Identity Platform

Identity Platform richiede la configurazione manuale nella console Google Cloud .

  1. Nella console Google Cloud , abilita l'API Identity Platform:

    Abilitare l'API

  2. Configura il progetto:

    1. In una nuova finestra, vai alla pagina Google Auth Platform > Panoramica.

      Vai alla panoramica

    2. Fai clic su Inizia e segui la procedura di configurazione del progetto.

    3. Nella finestra di dialogo Informazioni app:

      1. Fornisci il nome dell'applicazione.
      2. Seleziona una delle email dell'assistenza utente visualizzate.

    4. Nella finestra di dialogo Pubblico, seleziona Esterno.

    5. Nella finestra di dialogo Informazioni di contatto, inserisci un'email di contatto.

    6. Accetta le norme relative ai dati utente, poi fai clic su Crea.

  3. Crea e ottieni l'ID client OAuth e il segreto:

    1. Nella console Google Cloud , vai alla pagina API e servizi > Credenziali.

      Vai a credenziali

    2. Nella parte superiore della pagina, fai clic su Crea credenziali e seleziona OAuth client ID.

    3. In Tipo di applicazione, seleziona Applicazione web e fornisci il nome.

    4. Fai clic su Crea

    5. I valori client_id e client_secret verranno utilizzati nel passaggio successivo.

  4. Configura Google come fornitore:

    1. Nella console Google Cloud , vai alla pagina Provider di identità.

      Vai a Provider di identità

    2. Fai clic su Aggiungi un provider.

    3. Seleziona Google dall'elenco.

    4. Nelle impostazioni di configurazione dell'SDK web, inserisci i valori client_id e client_secret del passaggio precedente.

    5. Nella sezione Configura la tua applicazione, fai clic su Dettagli di configurazione.

  5. Copia la configurazione nella tua applicazione:

    • Copia i valori apiKey e authDomain in static/config.js dell'esempio per inizializzare l'SDK client di Identity Platform.

Deployment del servizio

Segui i passaggi per completare il provisioning e il deployment dell'infrastruttura:

  1. Crea un'istanza Cloud SQL con il database PostgreSQL utilizzando la console o la CLI:

    gcloud sql instances create CLOUD_SQL_INSTANCE_NAME \
    --database-version=POSTGRES_16 \
    --region=CLOUD_SQL_REGION \
    --cpu=2 \
    --memory=7680MB \
    --root-password=DB_PASSWORD

  2. Aggiungi i valori delle credenziali Cloud SQL a postgres-secrets.json:

    Node.js 

    {
  "CLOUD_SQL_CONNECTION_NAME": "PROJECT_ID:REGION:INSTANCE",
  "DB_NAME": "postgres",
  "DB_USER": "postgres",
  "DB_PASSWORD": "PASSWORD_SECRET"
}

    Python 

    {
  "CLOUD_SQL_CONNECTION_NAME": "PROJECT_ID:REGION:INSTANCE",
  "DB_NAME": "postgres",
  "DB_USER": "postgres",
  "DB_PASSWORD": "PASSWORD_SECRET"
}

    Java 

    {
  "spring.cloud.gcp.sql.instance-connection-name": "PROJECT_ID:REGION:INSTANCE",
  "spring.cloud.gcp.sql.database-name": "postgres",
  "spring.datasource.username": "postgres",
  "spring.datasource.password": "PASSWORD_SECRET"
}

  3. Crea un secret con controllo delle versioni utilizzando la console o la CLI:

    gcloud secrets create idp-sql-secrets \
    --replication-policy="automatic" \
    --data-file=postgres-secrets.json

  4. Crea un account di servizio per il server utilizzando la console o la CLI:

    gcloud iam service-accounts create idp-sql-identity

  5. Concedi i ruoli per l'accesso a Secret Manager e Cloud SQL utilizzando la console o la CLI:

    1. Consenti al account di servizio associato al server di accedere al secret creato:

      gcloud secrets add-iam-policy-binding idp-sql-secrets \
  --member serviceAccount:idp-sql-identity@PROJECT_ID.iam.gserviceaccount.com \
  --role roles/secretmanager.secretAccessor

    2. Consenti all'account di servizio associato al server di accedere a Cloud SQL:

      gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:idp-sql-identity@PROJECT_ID.iam.gserviceaccount.com \
  --role roles/cloudsql.client

  6. Crea un Artifact Registry:

    gcloud artifacts repositories create REPOSITORY \
    --repository-format docker \
    --location REGION
    • REPOSITORY è il nome del repository. Per ogni posizione del repository in un progetto, i nomi dei repository devono essere univoci.

  7. Crea l'immagine container utilizzando Cloud Build:

    Node.js 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql

    Python 

    gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql

    Java

    Questo esempio utilizza Jib per creare immagini Docker utilizzando strumenti Java comuni. Jib ottimizza le build dei container senza la necessità di un Dockerfile o di Docker installato. Scopri di più sulla creazione di container Java con Jib.

    1. Utilizza l'assistente per le credenziali gcloud per autorizzare Docker a eseguire il push su Artifact Registry. 

      gcloud auth configure-docker

    2. Utilizza il plug-in Jib Maven per creare ed eseguire il push del container in Artifact Registry. 

      mvn compile jib:build -Dimage=REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql

  8. Esegui il deployment dell'immagine container in Cloud Run utilizzando la console o la CLI. Tieni presente che il server viene implementato per consentire l'accesso non autenticato. In questo modo, l'utente può caricare il client e iniziare la procedura. Il server verifica manualmente il token ID aggiunto alla richiesta di voto, autenticando l'utente finale.

    gcloud run deploy idp-sql \
    --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/idp-sql \
    --allow-unauthenticated \
    --service-account idp-sql-identity@PROJECT_ID.iam.gserviceaccount.com \
    --add-cloudsql-instances PROJECT_ID:REGION:CLOUD_SQL_INSTANCE_NAME \
    --update-secrets CLOUD_SQL_CREDENTIALS_SECRET=idp-sql-secrets:latest

    Tieni presente anche i flag --service-account, --add-cloudsql-instances e --update-secrets, che specificano rispettivamente l'identità del servizio, la connessione all'istanza Cloud SQL e il nome del secret con la versione come variabile di ambiente.

Gli ultimi ritocchi

Identity Platform richiede di autorizzare l'URL del servizio Cloud Run come reindirizzamento consentito dopo l'accesso dell'utente:

  1. Modifica il provider Google facendo clic sull'icona a forma di penna nella pagina Provider di identità.

  2. Fai clic su Aggiungi dominio in Domini autorizzati nel riquadro a destra e inserisci l'URL del servizio Cloud Run.

    Puoi trovare l'URL del servizio nei log dopo la build o il deployment oppure puoi trovarlo in qualsiasi momento utilizzando:

    gcloud run services describe idp-sql --format 'value(status.url)'

  3. Vai alla pagina API e servizi > Credenziali.

    1. Fai clic sull'icona a forma di matita accanto all'ID client OAuth per modificarlo e sotto il pulsante Authorized redirect URIs click the Aggiungi URI.

    2. Nel campo, copia e incolla il seguente URL e fai clic sul pulsante Salva in fondo alla pagina.

    https://PROJECT_ID.firebaseapp.com/__/auth/handler

Prova

Per provare il servizio completo:

  1. Nel browser, vai all'URL fornito nel passaggio di deployment precedente.

  2. Fai clic sul pulsante Accedi con Google e segui il flusso di autenticazione.

  3. Aggiungi il tuo voto.

    Dovrebbe avere il seguente aspetto:

    L&#39;interfaccia utente mostra il conteggio dei voti per ogni squadra e un elenco dei voti.

Se scegli di continuare a sviluppare questi servizi, ricorda che hanno accesso Identity and Access Management (IAM) limitato al resto di Google Cloud e dovranno essere assegnati ruoli IAM aggiuntivi per accedere a molti altri servizi.