Utilizzare client OAuth personalizzati con IAP

Questo documento descrive quando e come utilizzare i client OAuth personalizzati per Identity-Aware Proxy (IAP).

Per impostazione predefinita, IAP utilizza client OAuth gestiti da Google per autenticare gli utenti. I client OAuth gestiti da Google possono essere utilizzati solo per gestire l'accesso per gli utenti interni che fanno parte di un'organizzazione.

Devi utilizzare una configurazione OAuth personalizzata per:

  • Gestisci l'accesso alle applicazioni abilitate per IAP per gli utenti esterni che non fanno parte della tua organizzazione.
  • Gestisci l'accesso alle applicazioni web che si trovano in progetti non inclusi in un' Google Cloud organizzazione.
  • Visualizzare informazioni sul brand personalizzate nelle schermate per il consenso durante l'autenticazione.

Puoi configurare i client OAuth personalizzati in IAP o direttamente sulla tua piattaforma.

Quando utilizzi client OAuth personalizzati, devi configurare la schermata per il consenso OAuth. Affinché il branding personalizzato venga visualizzato nella schermata per il consenso, devi sottoporre la tua applicazione a verifica da parte di Google. Per saperne di più sulla procedura di verifica, consulta Configurare la schermata per il consenso OAuth.

Quando configuri i client OAuth personalizzati, sei responsabile della creazione e della gestione delle credenziali, che include l'archiviazione sicura del client secret e la condivisione con i client autorizzati, se necessario.

Confronta i client OAuth gestiti da Google e i client OAuth personalizzati

I client OAuth gestiti da Google non possono accedere in modo programmatico alle applicazioni protette da IAP. Tuttavia, le applicazioni protette da IAP che utilizzano il client OAuth gestito da Google sono ancora accessibili a livello di programmazione utilizzando un client OAuth separato configurato tramite l'impostazione programmatic_clients o un JWT del service account.

La tabella seguente fornisce un confronto tra il client OAuth gestito da Google e un client OAuth personalizzato.

Client OAuth gestito da Google Client OAuth personalizzato
Utenti Solo interno Interni ed esterni
Brand Google Cloud brand Brand di proprietà del cliente
Configurazione OAuth Configurato da Google Configurato dal cliente
Credenziali OAuth Gestita da Google Gestita dal cliente
Accesso alle applicazioni Solo flusso del browser Flusso del browser e accesso programmatico

Configurare la pagina del branding

Per configurare la pagina di branding personalizzato utilizzando la console Google Cloud :

  1. Nella console Google Cloud , vai alla pagina Branding OAuth:

    Vai a Branding

  2. Fai clic su Inizia.

  3. In Nome app, inserisci il nome dell'applicazione per la schermata del consenso.

  4. In Email di assistenza utenti, inserisci l'indirizzo email dell'amministratore per l'assistenza.

  5. Per Pubblico, seleziona Interno per limitare l'accesso agli utenti all'interno dell'organizzazione o Esterno per consentire l'accesso agli utenti esterni all'organizzazione.

  6. In Informazioni di contatto, inserisci l'indirizzo email dell'amministratore da contattare per le app protette dai client OAuth. Configurerai i client OAuth in un passaggio successivo.

  7. Per creare la configurazione OAuth, fai clic su Crea.

Configurare client OAuth personalizzati in IAP

Questa sezione descrive come configurare i client OAuth personalizzati in IAP.

Puoi creare un client OAuth personalizzato per IAP utilizzando la consoleGoogle Cloud nei seguenti modi:

Indipendentemente dal metodo utilizzato, assicurati di aver configurato la pagina del branding prima di creare il client OAuth. Il formato URI di reindirizzamento richiesto è mostrato in entrambi i metodi.

Crea il client OAuth personalizzato

Questa sezione descrive come creare client OAuth personalizzati utilizzando la consoleGoogle Cloud . Puoi configurare client OAuth IAP personalizzati a qualsiasi livello della gerarchia delle risorse.

Per creare client OAuth personalizzati per una risorsa utilizzando la console Google Cloud , utilizza uno dei seguenti metodi:

Metodo 1: crea un client OAuth utilizzando la console Google Cloud

Utilizza questo metodo quando vuoi creare il client OAuth separatamente, ad esempio prima di configurare IAP per le tue risorse. Ciò richiede l'aggiunta manuale dell'URI di reindirizzamento IAP.

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

  2. Fai clic su Crea credenziali e poi seleziona ID client OAuth.

  3. Per Tipo di applicazione, seleziona Applicazione web.

  4. Nel campo Nome, inserisci un nome descrittivo per il client OAuth.

  5. Fai clic su Crea. Prendi nota dell'ID client generato.

  6. Dopo aver creato il client OAuth, vai alla sezione URI di reindirizzamento autorizzati della pagina dei dettagli del client OAuth per il client OAuth appena creato.

  7. Fai clic su Aggiungi URI e inserisci il seguente URI di reindirizzamento autorizzato specifico per IAP:

    https://iap.googleapis.com/v1/oauth/clientIds/YOUR_CLIENT_ID:handleRedirect

    Sostituisci YOUR_CLIENT_ID con l'ID client ottenuto nel passaggio precedente.

  8. Fai clic su Salva.

Metodo 2: crea un client OAuth utilizzando le credenziali generate automaticamente da IAP

Utilizza questo metodo per consentire a IAP di creare e configurare il client OAuth per te e aggiungere automaticamente l'URI di reindirizzamento richiesto.

  1. Nella console Google Cloud , vai alla pagina IAP.

    Vai a IAP

  2. Nella scheda Applicazioni, nell'elenco delle risorse, trova la risorsa che vuoi configurare.

    Per le risorse a livello di progetto:

    • Crea il client OAuth utilizzando la Google Cloud console:

      1. Nella colonna Azioni, fai clic su Altre opzioni > Impostazioni.

      2. Nella finestra di dialogo Impostazioni, seleziona OAuth personalizzato.

      3. Se non hai configurato una schermata per il consenso, procedi nel seguente modo:

        1. Fai clic su Configura schermata per il consenso.

        2. Segui le istruzioni per configurare la pagina del brand fornite in precedenza in questo documento.

      4. Nella finestra di dialogo delle impostazioni IAP, fai clic su Genera automaticamente le credenziali. IAP genera un nuovo client OAuth e un nuovo secret da utilizzare con questa risorsa. In Google Auth Platform, il campo URI di reindirizzamento autorizzati contiene una voce nel seguente formato:

        https://iap.googleapis.com/v1/oauth/clientIds/CLIENT_ID:handleRedirect

      5. Per accedere all'ID client e al client secret, fai clic su Scarica credenziali. Le credenziali vengono salvate in un file in formato JSON. Poiché il file contiene credenziali sensibili per l'accesso alle risorse, assicurati che sia protetto o eliminato.

      6. Per salvare la configurazione OAuth di IAP e applicare il client OAuth a IAP, fai clic su Salva.

Applicare client OAuth personalizzati a IAP

Questa sezione descrive come applicare i client OAuth a IAP. Puoi utilizzare questo metodo anziché applicare i clienti direttamente sulla tua piattaforma.

  1. Per creare il client OAuth personalizzato, segui le istruzioni della consoleGoogle Cloud fornite in precedenza in questo documento.

  2. Applica il client OAuth personalizzato.

    gcloud

    Per applicare il client OAuth personalizzato utilizzando gcloud CLI, procedi nel seguente modo:

    1. Crea un file YAML delle impostazioni.

      cat << EOF > iap-oauth.yaml
accessSettings:
oauthSettings:
  clientId: CLIENT_ID
  clientSecret: CLIENT_SECRET
EOF

      Sostituisci quanto segue:

      • CLIENT_ID: l'ID client delle credenziali OAuth generate in precedenza.
      • CLIENT_SECRET: il client secret delle credenziali OAuth generate in precedenza.

    2. Per impostare la configurazione OAuth, esegui una delle seguenti operazioni:

      • Per impostare la configurazione OAuth a livello di progetto, esegui questo comando:
      gcloud iap settings set iap-oauth.yaml

      Per impostare la configurazione a un altro livello della gerarchia delle risorse, utilizza uno dei seguenti flag anziché il flag --project. La configurazione di client OAuth personalizzati a un livello della gerarchia delle risorse fornisce lo stesso branding personalizzato a tutti i servizi eseguiti all'interno di quel livello.

      * <pre>--folder=<var>FOLDER_ID</var></pre>
* <code>--organization=<var>ORGANIZATION_ID</var></code>
      • Per impostare la configurazione su un servizio specifico, esegui questo comando:
      gcloud iap settings set iap-oauth.yaml \
    --project=PROJECT_ID \
    --resource-type= RESOURCE_TYPE \
    --region=REGION \
    --service=SERVICE_NAME

      Sostituisci quanto segue:

      • PROJECT_ID: l'ID della risorsa progetto. Per impostare la configurazione a un altro livello, utilizza uno dei seguenti flag anziché il flag --project:

        • --folder=FOLDER_ID
        • --organization=ORGANIZATION_ID

      • RESOURCE_TYPE: sostituisci con uno dei seguenti tipi di risorse, a seconda della risorsa:

        • app-engine
        • backend-services
        • cloud-run
        • compute
        • folder
        • forwarding-rule
        • iap_web
        • organization

      • REGION: la regione in cui esegui il servizio Cloud Run.

      • SERVICE_NAME: il nome del tuo servizio.

    Terraform

    Per applicare il client OAuth personalizzato utilizzando Terraform:

    resource "google_iap_settings" "iap_settings" {
name = IAP_RESOURCE_NAME
access_settings {
  oauth_settings {
      oauth_client_id = CLIENT_ID
      oauth_client_secret = CLIENT_SECRET
  }
}
}

    Sostituisci quanto segue:

    • IAP_RESOURCE_NAME: il nome della risorsa iap_settings per il servizio, nel seguente formato: projects/PROJECT_NUMBER/iap_web/REGION/services/SERVICE_NAME
    • CLIENT_ID: l'ID client delle credenziali OAuth generate in precedenza
    • CLIENT_SECRET: il client secret dalle credenziali OAuth che hai generato in precedenza

    API REST

    1. Crea un file JSON delle impostazioni.

      cat << EOF > iap-oauth.json
{
"accessSettings": {
  "oauthSettings": {
    "clientId": "CLIENT_ID",
    "clientSecret": "CLIENT_SECRET"
  }
}
}
EOF

      Sostituisci quanto segue:

      • CLIENT_ID: l'ID client delle credenziali OAuth generate in precedenza.
      • CLIENT_SECRET: il client secret delle credenziali OAuth generate in precedenza.

    2. Applica il file di impostazioni.

      curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/yaml" \
"https://iap.googleapis.com/v1/projects/cb-managed-ingress-demo/iap_web/forwarding_rule-us-central1/services/psc-fr:iapSettings?update_mask=iapSettings.accessSettings.oauthSettings.oauthClientId,iapSettings.accessSettings.oauthSettings.oauthClientSecret" \
-d @iap-oauth.json

Per verificare che le tue applicazioni web siano protette da IAP con i client OAuth, consulta Testare l'accesso.

Configurazione legacy dei client OAuth personalizzati su una risorsa

Le sezioni seguenti descrivono i metodi legacy per configurare client OAuth personalizzati in IAP per determinati tipi di risorse. Puoi saltare questa sezione se hai utilizzato il metodo descritto in precedenza in questo documento.

App Engine

Questa sezione descrive come attivare i client OAuth personalizzati su App Engine.

gcloud

Prima di configurare il progetto e IAP, devi disporre di una versione aggiornata di gcloud CLI. Per istruzioni su come installare gcloud CLI, vedi Installa gcloud CLI.

  1. Per l'autenticazione, utilizza Google Cloud CLI ed esegui il seguente comando. 
    gcloud auth login
  2. Per accedere, segui l'URL visualizzato.
  3. Dopo aver eseguito l'accesso, copia il codice di verifica visualizzato e incollalo nella riga di comando.
  4. Esegui questo comando per specificare il progetto che contiene la risorsa che vuoi proteggere con IAP. 
    gcloud config set project PROJECT_ID
  5. Segui le istruzioni riportate in Creazione di client OAuth per IAP per configurare la schermata per il consenso OAuth e creare il client OAuth.
  6. Salva l'ID client OAuth e il client secret.
  7. Per abilitare IAP, esegui questo comando. 
    gcloud iap web enable \
    --oauth2-client-id=CLIENT_ID \
    --oauth2-client-secret=CLIENT_SECRET \
    --resource-type=app-engine

Dopo aver abilitato IAP, puoi utilizzare gcloud CLI per modificare il criterio di accesso IAP utilizzando il ruolo IAM roles/iap.httpsResourceAccessor. Scopri di più sulla gestione di ruoli e autorizzazioni.

API

  1. Segui le istruzioni riportate in Creazione di client OAuth per IAP per configurare la schermata per il consenso OAuth e creare il client OAuth.

  2. Salva l'ID client OAuth e il client secret.

  3. Esegui questo comando per preparare un file settings.json. 

    cat << EOF > settings.json
{
"iap":
  {
    "enabled": true,
    "oauth2ClientId": "CLIENT_ID",
    "oauth2ClientSecret":" CLIENT_SECRET"
  }
}
EOF

  4. Esegui questo comando per abilitare IAP. 

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @settings.json \
"https://appengine.googleapis.com/v1/apps/PROJECT_ID?updateMask=iap"

Dopo aver abilitato IAP, puoi utilizzare Google Cloud CLI per modificare la policy di accesso IAP utilizzando il ruolo IAM roles/iap.httpsResourceAccessor. Scopri di più sulla gestione di ruoli e autorizzazioni.

GKE

Questa sezione descrive come attivare i client OAuth personalizzati su GKE.

Configura BackendConfig

Se esegui cluster GKE versione 1.24 o successive, puoi configurare IAP e GKE utilizzando l'API Kubernetes Gateway. Per istruzioni, vedi Configurare IAP.

  1. Segui le istruzioni riportate in Creazione di client OAuth per IAP per configurare la schermata per il consenso OAuth e creare il client OAuth.

  2. Crea un secret di Kubernetes per eseguire il wrapping del client OAuth. 

    kubectl create secret generic MY_SECRET --from-literal=client_id=CLIENT_ID \
  --from-literal=client_secret=CLIENT_SECRET
    Sostituisci quanto segue:

    • MY_SECRET: il nome del secret da creare
    • CLIENT_ID: L'ID client OAuth
    • CLIENT_SECRET: Il client secret OAuth

    Dovresti ricevere una conferma, come l'output seguente, che indica che il secret è stato creato correttamente: 

    secret "MY_SECRET" created

  3. Aggiungi le credenziali OAuth a BackendConfig. 

    apiVersion: cloud.google.com/v1
kind: BackendConfig
metadata:
  name: CONFIG_DEFAULT
  namespace: my-namespace
spec:
iap:
  enabled: true
  oauthclientCredentials:
    secretName: MY_SECRET

  4. Attiva IAP associando le porte di servizio a BackendConfig. Consulta Associazione di BackendConfig al tuo Ingress. Un modo per creare questa associazione è impostare come predefiniti tutte le porte per il servizio in BackendConfig. Per farlo, aggiungi la seguente annotazione alla risorsa di servizio: 

    metadata:
  annotations:
      cloud.google.com/backend-config: '{"default": "CONFIG_DEFAULT"}'

Dopo aver abilitato IAP, puoi utilizzare gcloud CLI per modificare il criterio di accesso IAP utilizzando il ruolo IAM roles/iap.httpsResourceAccessor. Scopri di più sulla gestione di ruoli e autorizzazioni.

Risoluzione dei problemi

Se il secretName a cui hai fatto riferimento non esiste o non è strutturato correttamente, verrà visualizzato uno dei seguenti messaggi di errore:

  • BackendConfig default/config-default is not valid: error retrieving secret "foo": secrets "foo" not found. Per risolvere questo errore, assicurati di aver creato correttamente il secret di Kubernetes come descritto nel passaggio 2.

  • BackendConfig default/config-default is not valid: secret "foo" missing client_secret data. Per risolvere questo errore, assicurati di aver creato correttamente le credenziali OAuth. Inoltre, assicurati di aver fatto riferimento alle chiavi client_id e client_secret corrette.

Servizio di backend del bilanciatore del carico

Per gli utenti di Compute Engine e Cloud Run, questa sezione descrive come configurare i client OAuth in IAP per il servizio di backend del bilanciatore del carico.

gcloud

Prima di configurare il progetto e IAP, devi disporre di una versione aggiornata di gcloud CLI. Per istruzioni su come installare gcloud CLI, vedi Installa gcloud CLI.

  1. Per l'autenticazione, utilizza Google Cloud CLI ed esegui il seguente comando. 
    gcloud auth login
  2. Per accedere, segui l'URL visualizzato.
  3. Dopo aver eseguito l'accesso, copia il codice di verifica visualizzato e incollalo nella riga di comando.
  4. Esegui questo comando per specificare il progetto che contiene la risorsa che vuoi proteggere con IAP. 
    gcloud config set project PROJECT_ID
  5. Segui le istruzioni riportate in Creazione di client OAuth per IAP per configurare la schermata per il consenso OAuth e creare il client OAuth.
  6. Salva l'ID client OAuth e il client secret.
  7. Per abilitare IAP, esegui il comando con ambito globale o regionale.

    Ambito globale 
    gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --global \
    --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET
     Ambito regionale 
    gcloud compute backend-services update BACKEND_SERVICE_NAME \
    --region REGION_NAME \
    --iap=enabled,oauth2-client-id=CLIENT_ID,oauth2-client-secret=CLIENT_SECRET

Dopo aver abilitato IAP, puoi utilizzare gcloud CLI per modificare il criterio di accesso IAP utilizzando il ruolo IAM roles/iap.httpsResourceAccessor. Scopri di più sulla gestione di ruoli e autorizzazioni.

API

  1. Segui le istruzioni riportate in Creazione di client OAuth per IAP per configurare la schermata per il consenso OAuth e creare il client OAuth.

  2. Salva l'ID client OAuth e il client secret.

  3. Esegui questo comando per preparare un file settings.json. 

    cat << EOF > settings.json
{
"iap":
  {
    "enabled": true,
    "oauth2ClientId": "CLIENT_ID",
    "oauth2ClientSecret": "CLIENT_SECRET"
  }
}
EOF

  4. Esegui questo comando per abilitare IAP. 

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d @settings.json \
"https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/REGION/backendServices/BACKEND_SERVICE_NAME"

Dopo aver abilitato IAP, puoi utilizzare gcloud CLI per modificare il criterio di accesso IAP utilizzando il ruolo IAM roles/iap.httpsResourceAccessor. Scopri di più sulla gestione di ruoli e autorizzazioni.

Controlla l'accesso

Dopo aver configurato il client OAuth personalizzato, puoi verificare che IAP lo utilizzi per proteggere il tuo servizio procedendo nel seguente modo:

  1. Nella pagina IAP, nella scheda Applicazioni, visualizza le applicazioni gestite da IAP.

  2. Accedi all'URL di una delle applicazioni. Se accedi all'applicazione per la prima volta dopo aver configurato la schermata per il consenso, visualizzi la schermata per il consenso che hai configurato in precedenza.