Hosting di una pagina di accesso con Cloud Run

Per utilizzare identità esterne con Identity-Aware Proxy (IAP), la tua app deve avere una pagina di accesso. IAP reindirizzerà gli utenti a questa pagina per l'autenticazione prima che possano accedere alle risorse sicure.

Questo documento mostra come eseguire il deployment e personalizzare una pagina di accesso predefinita utilizzando Cloud Run. Si tratta del modo più rapido per iniziare a utilizzare identità esterne e non richiede la scrittura di codice.

Puoi anche creare una pagina di accesso autonomamente. Creare la tua pagina è più difficile, ma aumenta il tuo controllo sul flusso di autenticazione e sull'esperienza utente. Per saperne di più, consulta gli articoli Creazione di una pagina di accesso con FirebaseUI e Creazione di una pagina di accesso personalizzata.

Limitazioni della pagina di accesso

Non puoi utilizzare la pagina di accesso predefinita se nel progetto è abilitata la protezione dall'enumerazione delle email.

Se nel progetto è attiva la protezione dall'enumerazione delle email, disabilita la protezione dall'enumerazione delle email prima di continuare con le procedure descritte in questo documento.

Prima di iniziare

  • Abilitare l'API Compute Engine.

    Abilita l'API Compute Engine

  • Abilita le identità esterne e seleziona l'opzione Crea una pagina di accesso per me durante la configurazione. In questo modo, Cloud Run e FirebaseUI creano una pagina di accesso per te.

  • Assicurati che l'account di servizio utilizzato da Cloud Run, PROJECT_NUMBER-compute@developer.gserviceaccount.com, abbia i seguenti ruoli predefiniti:

    • roles/identitytoolkit.viewer
    • roles/iap.settingsAdmin
    • roles/compute.networkViewer

Impostare l'URL di reindirizzamento della pagina ospitata

Le pagine di accesso ospitate utilizzano il proprio dominio come dominio di autenticazione Firebase per garantire che l'accesso tramite reindirizzamento funzioni correttamente in tutti gli ambienti. Devi aggiungere l'URL della pagina ospitata come URL di reindirizzamento autorizzato nella configurazione del provider.

Per aggiungere l'URL della pagina di accesso ospitata come URL di reindirizzamento autorizzato, procedi nel seguente modo:

  1. Copia l'URL di accesso dopo aver selezionato l'applicazione.

  2. Nella console Google Cloud, vai alla pagina Credenziali.

    Vai a Credenziali

  3. Aggiungi LOGIN_URL/__/auth/handler come uno degli URI di reindirizzamento autorizzati per il client OAuth 2.0 dell'app. Seleziona lo stesso ID client OAuth e la stessa chiave segreta che hai utilizzato durante la configurazione del provider.

  4. Se la tua app utilizza altri provider SAML e OIDC, aggiungi LOGIN_URL/__/auth/handler come URI di reindirizzamento autorizzato o URL ACS.

In alternativa, puoi utilizzare PROJECT_ID.firebaseapp.com anziché LOGIN_URL/__/auth/handler come dominio di autenticazione personalizzando la pagina di accesso con il flusso di accesso popup.

Per implementare il flusso di accesso popup per la tua pagina:

  1. Fai clic su Personalizza pagina.

  2. Nel file di configurazione in formato JSON, imposta authDomain su PROJECT_ID.firebaseapp.com e signInFlow su popup.

  3. Per salvare la configurazione, fai clic su Salva.

Sostituisci quanto segue:

  • LOGIN_URL: il dominio della tua pagina di accesso ospitata
  • PROJECT_ID: ID progetto Firebase

Di seguito è riportato un esempio di configurazione del flusso di accesso popup:

{
  "AIzaSyC5DtmRUR...": {
    "authDomain": "example.firebaseapp.com",
    "displayMode": "optionFirst",
    ...
    ...
    "tenants": {
      "tenant-a-id": {
        "fullLabel": "Company A Portal",
        "displayName": "Company A",
        ...
        ...
        "signInFlow": "popup",
        ...
        ...
      }
    }
  }
}

Per ulteriori informazioni sulle best practice di reindirizzamento e sul partizionamento dello spazio di archiviazione, vedi Best practice per l'utilizzo di signInWith Redirect sui browser che bloccano l'accesso allo spazio di archiviazione di terze parti.

Test della pagina di accesso

La pagina di accesso iniziale creata da IAP è completamente funzionante. Per verificarlo:

  1. Accedi a una risorsa protetta da IAP. Il sistema dovrebbe reindirizzarti automaticamente alla pagina di accesso.

  2. Seleziona un tenant e un provider con cui accedere. Se non vedi alcun tenant o provider nell'elenco, assicurati di averne configurato uno utilizzando Identity Platform.

  3. Accedi con le tue credenziali.

Il sistema ti reindirizzerà alla risorsa protetta.

Personalizzazione della pagina di accesso

Puoi personalizzare la pagina di accesso utilizzando un file di configurazione JSON. Ecco alcune opzioni:

  • Aggiunta di un'intestazione e un logo alla pagina di accesso.
  • Specifica i tenant e i provider disponibili.
  • Personalizzazione delle icone e dello stile di ogni pulsante del tenant e del provider.
  • Aggiunta di link alle norme sulla privacy e ai Termini di servizio dell'app.

Le seguenti sezioni spiegano come accedere al file di configurazione JSON e aggiornarlo.

Ottenere un token di accesso

Per amministrare la pagina di accesso, hai bisogno di un token di accesso Google. Il modo più semplice per ottenerne uno è abilitare Google come provider per Identity Platform. Se la tua app usa già Google come provider di identità, puoi saltare questa sezione.

  1. Vai alla pagina Provider Identity Platform nella console Google Cloud.

    Vai alla pagina dei provider Identity Platform

  2. Fai clic su Add a Provider (Aggiungi un provider).

  3. Seleziona Google dall'elenco dei fornitori.

  4. Configura l'ID client web e il client secret web:

    1. Apri la pagina IAP in una scheda separata.

      Vai alla pagina IAP

    2. Espandi il menu Visualizza altro per la risorsa, quindi fai clic su Modifica client OAuth.

    3. Copia i campi Client ID e Client secret nella configurazione del provider Google per Identity Platform.

    4. Aggiungi l'URL di reindirizzamento di Identity Platform all'elenco degli URI di reindirizzamento autorizzati per il client OAuth. L'URL ha il formato https://PROJECT_ID.firebaseapp.com/__/auth/handler.

  5. Fai clic su Salva in entrambe le pagine.

Accesso al pannello di amministrazione

La configurazione JSON per la pagina di accesso ospitata da Cloud Run. I passaggi seguenti spiegano come accedere al pannello. Tieni presente che dovrai disporre del ruolo Amministratore Storage (roles/storage.admin).

  1. Vai alla pagina IAP nella console Google Cloud.

    Vai alla pagina IAP

  2. Seleziona la risorsa dall'elenco.

  3. Apri l'URL indicato in Personalizza pagina nel riquadro delle informazioni. Dovrebbe avere un aspetto simile a https://servicename-xyz-uc.a.run.app/admin.

  4. Accedi con lo stesso Account Google che hai utilizzato per configurare IAP. Viene visualizzato un editor di testo contenente il file di configurazione JSON.

Modifica della configurazione

Lo schema di configurazione per la pagina di accesso si basa su FirebaseUI e ne eredita molte proprietà. Il codice seguente mostra una configurazione di esempio con tre tenant:

{
  "AIzaSyC5DtmRUR...": {
    "authDomain": "awesomeco.firebaseapp.com",
    "displayMode": "optionFirst",
    "selectTenantUiTitle": "Awesome Company Portal",
    "selectTenantUiLogo": "https://awesome.com/abcd/logo.png",
    "styleUrl": "https://awesome.com/abcd/overrides/stylesheet.css",
    "tosUrl": "https://awesome.com/abcd/tos.html",
    "privacyPolicyUrl": "https://awesome.com/abcd/privacypolicy.html",
    "tenants": {
      "tenant-a-id": {
        "fullLabel": "Company A Portal",
        "displayName": "Company A",
        "iconUrl": "https://companya.com/img/icon.png",
        "logoUrl": "https://companya.com/img/logo.png",
        "buttonColor": "#007bff",
        "signInOptions": [
          {
            "provider": "password",
            "requireDisplayName": false,
            "disableSignUp": {
              "status": true,
              "adminEmail": "admin@example.com",
              "helpLink": "https://www.example.com/trouble_signing_in"
            }
          },
          "facebook.com",
          "google.com",
          "microsoft.com",
          {
            "provider": "saml.okta-cicp-app",
            "providerName": "Corp Account",
            "fullLabel": "Employee Corporate Login",
            "buttonColor": "#ff0000",
            "iconUrl": "https://companya.com/abcd/icon-1.png"
          },
          {
            "provider": "oidc.okta-oidc",
            "providerName": "Contractor Account",
            "fullLabel": "Contractor Account Portal",
            "buttonColor": "#00ff00",
            "iconUrl": "https://companya.com/abcd/icon-2.png"
          }
        ],
        "tosUrl": "https://companya.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companya.com/abcd/privacypolicy.html"
      },
      "tenant-b-id": {
        "fullLabel": "Company B Portal",
        "displayName": "Company B",
        "iconUrl": "https://companyb.com/img/icon.png",
        "logoUrl": "https://companyb.com/img/logo.png",
        "buttonColor": "#007bff",
        "immediateFederatedRedirect": true,
        "signInOptions": [
          {
            "provider": "saml.okta-bla-app",
            "providerName": "Corp Account",
            "buttonColor": "#0000ff",
            "iconUrl": "https://companyb.com/abcd/icon.png"
          }
        ],
        "tosUrl": "https://companyb.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companyb.com/abcd/privacypolicy.html"
      },
      "tenant-c-id": {
        "fullLabel": "Company C Portal",
        "displayName": "Company C",
        "iconUrl": "https://companyc.com/img/icon.png",
        "logoUrl": "https://companyc.com/img/logo.png",
        "buttonColor": "#007bff",
        "immediateFederatedRedirect": true,
        "signInOptions": [
          {
            "provider": "password",
            "requireDisplayName": false
          },
          {
            "provider": "google.com",
            "scopes": ["scope1", "scope2", "https://example.com/scope3"],
            "loginHintKey": "login_hint",
            "customParameters": {
              "prompt": "consent",
            },
          }
        ],
        "tosUrl": "https://companyc.com/abcd/tos.html",
        "privacyPolicyUrl": "https://companyc.com/abcd/privacypolicy.html",
        "adminRestrictedOperation": {
          "status": true,
          "adminEmail": "admin@example.com",
          "helpLink": "https://www.example.com/trouble_signing_in"
        }
      },
    }
  }
}

Per un elenco completo delle proprietà disponibili, consulta la documentazione di riferimento.

Override CSS

Puoi utilizzare la proprietà styleUrl per specificare un file CSS personalizzato. Gli stili in questo file sostituiranno il CSS predefinito. Il file deve essere accessibile pubblicamente utilizzando HTTPS (ad esempio ospitato in un bucket Cloud Storage).

L'esempio seguente illustra l'override del CSS predefinito:

/** Change header title style. */
.heading-center {
  color: #7181a5;
  font-family: Arial, Helvetica, sans-serif;
  font-size: 20px;
  font-weight: bold;
}

/** Use round edged borders for container. */
.main-container {
  border-radius: 5px;
}

/** Change page background color. */
body {
  background-color: #f8f9fa;
}

Riesecuzione del deployment dell'istanza Cloud Run

In alcuni casi, potresti voler eseguire nuovamente il deployment dell'istanza Cloud Run che ospita la pagina di accesso. Ecco alcuni scenari di esempio:

  • Aggiunta, modifica o rimozione dei provider di identità
  • Modifica delle configurazioni dei tenant
  • Imposta le variabili di ambiente
  • Aggiornamento dell'immagine container alla versione più recente

L'aggiornamento e la nuova esecuzione del deployment dell'immagine container ti consentono di avere a disposizione le correzioni di bug e le patch di sicurezza più recenti. Puoi visualizzare l'elenco delle modifiche tra le versioni su GitHub.

Puoi recuperare la versione corrente del container di cui è stato eseguito il deployment utilizzando l'endpoint /versionz. Ad esempio:

curl 'https://servicename-xyz-uc.a.run.app/versionz'

Per eseguire nuovamente il deployment dell'istanza Cloud Run:

  1. Vai alla pagina Cloud Run nella console Google Cloud.

    Vai alla pagina di Cloud Run

  2. Seleziona l'istanza che ospita la pagina di accesso.

  3. Fai clic su Modifica ed esegui il deployment di nuova revisione.

  4. Facoltativamente, specifica le impostazioni avanzate per la revisione o aggiungi una variabile di ambiente facendo clic sulla scheda Variabili e secret.

  5. Fai clic su Esegui il deployment.

Opzioni avanzate

Personalizzazione della pagina di accesso in modo programmatico

Oltre a utilizzare la console /admin, puoi aggiornare la configurazione JSON in modo programmatico.

Per ottenere la configurazione attuale, utilizza l'endpoint /get_admin_config. Ad esempio:

curl -H 'Authorization: Bearer [TOKEN]'
  'https://servicename-xyz-uc.a.run.app/get_admin_config'

Per aggiornare la configurazione, utilizza /set_admin_config. Ad esempio:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' -H "Content-type: application/json"
  -d '[UPDATED-CONFIG]' 'https://servicename-xyz-uc.a.run.app/set_admin_config'

Entrambe le chiamate REST richiedono l'ambito https://www.googleapis.com/auth/devstorage.read_write e deve essere collegato un token OAuth valido all'intestazione Authorization.

Imposta le variabili di ambiente

Puoi impostare variabili di ambiente sull'istanza Cloud Run, per personalizzare le impostazioni avanzate. Nella seguente tabella sono elencate le variabili disponibili:

Variabile Descrizione
DEBUG_CONSOLE Un valore booleano (0 o 1) che indica se registrare tutti gli errori e i dettagli delle richieste di rete. I dati sensibili non verranno registrati. Disattivato (0) per impostazione predefinita.
UI_CONFIG Una stringa contenente la configurazione JSON per la pagina di accesso. L'utilizzo di questa variabile al posto del riquadro /admin evita di leggere e scrivere in Cloud Storage quando si accede alla configurazione. Le configurazioni non valide vengono ignorate. L'utilizzo del riquadro /admin per convalidare il codice JSON prima di impostare questa variabile può aiutare a ridurre al minimo gli errori di sintassi.
GCS_BUCKET_NAME Una stringa che sostituisce il bucket Cloud Storage predefinito utilizzato per archiviare la configurazione JSON. Il file è denominato config.json e la posizione predefinita è gcip-iap-bucket-[CLOUD-RUN-SERVICE-NAME]-[PROJECT-NUMBER].
ALLOW_ADMIN Un valore booleano (0 o 1) che indica se consentire l'accesso al riquadro di configurazione /admin. Abilitato (1) per impostazione predefinita.

Dopo aver aggiornato le variabili, prima che le modifiche abbiano effetto, dovrai eseguire il deployment di una nuova revisione dell'istanza Cloud Run. Per ulteriori informazioni sulle variabili di ambiente, consulta la documentazione di Cloud Run.

Personalizzazione del dominio

Per impostazione predefinita, gli utenti vedranno l'URL dell'istanza Cloud Run quando accedono. Per specificare invece un dominio personalizzato:

  1. Segui i passaggi in Mappatura di domini personalizzati per impostare un dominio personalizzato per l'istanza Cloud Run.

  2. Configura IAP per l'utilizzo del nuovo URL di autenticazione:

    1. Vai alla pagina IAP nella console Google Cloud.

      Vai alla pagina IAP

    2. Seleziona la risorsa protetta da IAP.

    3. Nel riquadro laterale, seleziona l'icona Modifica accanto al campo URL di accesso.

    4. Seleziona Usa una pagina di accesso ospitata esistente e scegli il tuo dominio dal menu a discesa.

    5. Fai clic su Salva.

Utilizzo di un'unica pagina di accesso per più risorse IAP

Puoi proteggere più risorse IAP utilizzando la stessa pagina di accesso. In questo modo ridurrai il lavoro associato alla gestione di più configurazioni.

Per riutilizzare una pagina di accesso:

  1. Segui i passaggi riportati in questo articolo per eseguire il deployment della pagina di autenticazione per la prima risorsa protetta da IAP.

  2. Abilita IAP per la seconda risorsa. Quando ti viene chiesto di specificare una pagina di accesso, seleziona Fornirò una pagina personalizzata e inserisci l'URL del servizio Cloud Run come URL.

  3. Esegui di nuovo il deployment del servizio Cloud Run.

Risoluzione dei problemi

La pagina di accesso non funziona sui browser che disattivano i cookie di terze parti o implementano il partizionamento dello spazio di archiviazione.

Per risolvere il problema:

  1. Esegui nuovamente il deployment della pagina di accesso. La versione più recente della pagina di accesso utilizza il dominio della pagina di accesso come authDomain.

  2. Personalizza la configurazione della pagina di accesso per assicurarti che authDomain sia impostato come URL della pagina di accesso della tua applicazione protetta da IAP.

    {
  "AIzaSyC5DtmRUR...": {
    "authDomain": "LOGIN_URL",
    ...
  }
}

Passaggi successivi