Utilizzare provider di identità esterni per l'autenticazione in GKE

Autopilot Standard

Questa pagina mostra come configurare l'autenticazione ai cluster Google Kubernetes Engine (GKE) da provider di identità esterni (IdP).

Questa pagina è rivolta agli amministratori e agli operatori della piattaforma e agli amministratori di identità e account che utilizzano un IdP esterno che supporta OpenID Connect (OIDC) o Security Assertion Markup Language (SAML) 2.0.

Prima di leggere questa pagina, assicurati di avere familiarità con i seguenti concetti di autenticazione e OpenID:

• OAuth 2.0
• SAML 2.0
• OpenID Connect
• Ambiti e claim OIDC
• RBAC di Kubernetes

Metodi di autenticazione IdP esterno in GKE

Consigliato: federazione delle identità per la forza lavoro

La federazione delle identità per la forza lavoro è una funzionalità IAM che ti consente di autenticarti su Google Cloud da qualsiasi IdP esterno che supporti OIDC o SAML 2.0. La federazione delle identità per la forza lavoro non richiede alcuna installazione all'interno del cluster, funziona con i cluster Autopilot e i cluster Standard ed è integrata in Google Cloud. Per maggiori dettagli, consulta la documentazione di IAM sulla federazione delle identità per la forza lavoro.

Non consigliato: servizio di identità per GKE (deprecato)

Attenzione: a partire dal 1° luglio 2026, Identity Service for GKE è deprecato e non è supportato in GKE 1.37 e versioni successive. Per saperne di più, consulta Ritiro di Identity Service for GKE.

Solo nei cluster GKE Standard, GKE supporta anche Identity Service for GKE. Servizio di identità per GKE è limitato agli IdP OIDC e installa componenti aggiuntivi nel cluster. GKE consiglia vivamente di utilizzare la federazione delle identità della forza lavoro anziché il servizio di identità per GKE. Tieni presente anche una limitazione nota di Identity Service for GKE che impedisce la scalabilità automatica.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti attività:

• Abilita l'API Google Kubernetes Engine.
Abilita l'API Google Kubernetes Engine
• Per utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il comando gcloud components update. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.
  Nota: per le installazioni esistenti di gcloud CLI, assicurati di impostare la proprietà compute/region. Se utilizzi principalmente cluster zonali, imposta invece compute/zone. Se imposti una località predefinita, puoi evitare errori in gcloud CLI come il seguente: One of [--zone, --region] must be supplied: Please specify location. Potresti dover specificare la posizione in determinati comandi se la posizione del cluster è diversa da quella predefinita che hai impostato.

Considerazioni

I sistemi headless non sono supportati né con la federazione delle identità per la forza lavoro né con il servizio di identità per GKE. Un flusso di autenticazione basato su browser ti chiede il consenso e l'autorizzazione del tuo account utente.

Utilizza la federazione delle identità per la forza lavoro in GKE

Per utilizzare la federazione delle identità per la forza lavoro nei cluster GKE, segui questi passaggi:

1. Configura la federazione delle identità per la forza lavoro per la tua organizzazione e l'IdP esterno. Per istruzioni, consulta Configura la federazione delle identità per la forza lavoro.
2. Configura l'accesso dal tuo IdP esterno alla console della federazione delle identità per la forza lavoro Google Cloud . Per maggiori dettagli, consulta Configura l'accesso degli utenti alla console (federata).

3. Configura l'accesso degli utenti utilizzando uno dei seguenti meccanismi di autorizzazione:

   • RBAC di Kubernetes
   • Policy di autorizzazione IAM

4. Chiedi agli utenti di accedere ai cluster completando i seguenti passaggi:

   1. Accedi a gcloud CLI con l'identità federata.
   2. Configura kubectl per l'autenticazione in un cluster specifico eseguendo gcloud container clusters get-credentials.

Configura l'accesso degli utenti ai cluster utilizzando RBAC

Google Cloud utilizza gli identificatori di entità per identificare gli utenti nei tuoi pool di identità della forza lavoro. Puoi fare riferimento a questi identificatori delle entità nelle policy RBAC di Kubernetes o nelle policy IAM per concedere autorizzazioni a singoli utenti o a gruppi di utenti. Con RBAC, non puoi fare riferimento ad altre asserzioni personalizzate contenute nei token IdP. RBAC supporta gli identificatori dei principali solo per utenti e gruppi.

La seguente tabella mostra esempi di identificatori di entità per singoli utenti e per gruppi:

Identità	Identificatore entità
Utente singolo	principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/subject/SUBJECT_ATTRIBUTE_VALUE Sostituisci quanto segue: WORKFORCE_IDENTITY_POOL: il nome del pool di identità della forza lavoro. SUBJECT_ATTRIBUTE_VALUE: il valore di un attributo nell'asserzione dell'oggetto del token di identità. Ad esempio, potrebbe essere il valore del campo NameID in un'asserzione SAML 2.0. Ad esempio: principal://iam.googleapis.com/locations/global/workforcePools/full-time-employees/subject/[e-mail]
Tutti gli utenti di un gruppo	principalSet://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_IDENTITY_POOL/group/GROUP_NAME Sostituisci quanto segue: WORKFORCE_IDENTITY_POOL: il nome del pool di identità della forza lavoro. GROUP_NAME: il nome di un gruppo di cui l'utente che esegue l'autenticazione è membro. L'asserzione nel token IdP deve avere una mappatura degli attributi all'attributo Google Cloud google.groups. Ad esempio: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre

Per ogni identificatore di entità supportato dalla federazione delle identità per la forza lavoro, consulta Rappresenta gli utenti del pool di forza lavoro nelle policy IAM.

L'esempio seguente mostra come concedere l'accesso di sola lettura a livello di cluster ai secret a qualsiasi entità nel pool di forza lavoro full-time-employees che fa parte del gruppo sre nel token IdP.

1. Salva il seguente manifest ClusterRole come secret-viewer-cluster-role.yaml:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: secret-viewer
   rules:
   - apiGroups: [""]
     resources: ["secrets"]
     verbs: ["get", "watch", "list"]
   

   Qualsiasi entità a cui associ questo ClusterRole può visualizzare i secret.

2. Salva il seguente manifest ClusterRoleBinding come secret-viewer-cluster-role-binding.yaml:

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name:  users-view-secrets
   subjects:
   - kind: Group
     name: principalSet://iam.googleapis.com/locations/global/workforcePools/full-time-employees/group/sre
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: secret-viewer
     apiGroup: rbac.authorization.k8s.io
   

   Questo ClusterRoleBinding concede il ClusterRole secret-viewer a qualsiasi utente che fa parte del gruppo sre.

3. Esegui il deployment di ClusterRole e ClusterRoleBinding:

   kubectl apply -f secret-viewer-cluster-role.yaml
   kubectl apply -f secret-viewer-cluster-role-binding.yaml
   

Accedi ed esegui l'autenticazione nel cluster

1. Chiedi all'utente di accedere utilizzando Google Cloud CLI.

2. L'utente può configurare kubectl per l'autenticazione nel cluster utilizzando quanto segue:

   gcloud container clusters get-credentials
   

Utilizza Identity Service for GKE

Attenzione: a partire dal 1° luglio 2026, il servizio di identità per GKE è deprecato e non è supportato in GKE 1.37 e versioni successive. Utilizza invece la federazione delle identità per la forza lavoro. Per saperne di più, consulta Ritiro del servizio di identità per GKE.

Per configurare e utilizzare il servizio di identità per GKE sul tuo cluster GKE in modalità Standard, gli amministratori del cluster devono:

1. Abilita Identity Service for GKE su un cluster.
2. Configura il servizio di identità per GKE.
3. Crea una policy RBAC per il tuo cluster.

Dopo che gli amministratori del cluster hanno configurato Identity Service for GKE, gli sviluppatori possono accedere ed eseguire l'autenticazione nel cluster.

Oggetti Kubernetes creati da Identity Service per GKE

La tabella seguente descrive gli oggetti Kubernetes creati quando attivi il servizio di identità per GKE su un cluster:

Oggetti Kubernetes
anthos-identity-service	Namespace Utilizzato per i deployment del servizio di identità per GKE.
kube-public	Namespace Utilizzato per il file di configurazione del client default.
gke-oidc-envoy	LoadBalancer L'endpoint per le richieste OIDC. Esterno per impostazione predefinita. Se creato in un cluster senza endpoint IP esterno, l'endpoint è interno al Virtual Private Cloud del cluster. Creata nello spazio dei nomi anthos-identity-service.
gke-oidc-service	ClusterIP Facilita la comunicazione tra il deployment gke-oidc-envoy e il deployment gke-oidc-service. Creata nello spazio dei nomi anthos-identity-service.
gke-oidc-envoy	Deployment Esegue un proxy esposto al bilanciatore del carico gke-oidc-envoy. Comunica con gke-oidc-service per convalidare i token di identità. Agisce come proxy per il server API Kubernetes e simula l'identità degli utenti quando trasmette le richieste al server API. Creata nello spazio dei nomi anthos-identity-service.
gke-oidc-service	Deployment Convalida i token di identità e fornisce un webhook di ammissione di convalida per le risorse ClientConfig. Creata nello spazio dei nomi anthos-identity-service.
gke-oidc-operator	Deployment Riconcilia la configurazione del client e il bilanciatore del carico gke-oidc-envoy. Creata nello spazio dei nomi anthos-identity-service.
gke-oidc-certs	Secret Contiene l'autorità di certificazione (CA) del cluster e i certificati TLS per LoadBalancer. Creato nello spazio dei nomi anthos-identity-service
default	ClientConfig CRD Contiene parametri OIDC come il metodo di autenticazione preferito, la configurazione del provider di identità e le mappature delle attestazioni di utenti e gruppi. Utilizzato per la convalida del token di identità. Utilizzato dagli amministratori del cluster per configurare le impostazioni OIDC prima della distribuzione agli sviluppatori. Creato nello spazio dei nomi kube-public

Abilita Identity Service for GKE su un cluster

Per impostazione predefinita, Identity and Access Management (IAM) è configurato come provider di identità per l'autenticazione del cluster. Se vuoi utilizzare OIDC con provider di identità di terze parti, puoi abilitare il servizio di identità per GKE su cluster nuovi o esistenti utilizzando Google Cloud CLI.

Nota: affinché il servizio di identità per GKE funzioni correttamente, GKE esegue il deployment dei pod sui nodi con autorizzazioni RBAC elevate, come la possibilità di assumere l'identità di utenti e gruppi. Queste autorizzazioni sono necessarie per consentire a Identity Service for GKE di facilitare la convalida dell'identità e la comunicazione in base alla tua configurazione.

Abilita il servizio di identità per GKE su un nuovo cluster

Per creare un cluster con Identity Service for GKE abilitato, esegui il seguente comando:

gcloud container clusters create CLUSTER_NAME \
    --enable-identity-service

Sostituisci CLUSTER_NAME con il nome del nuovo cluster.

Abilita Identity Service for GKE su un cluster esistente

Per abilitare Identity Service for GKE su un cluster esistente, esegui il seguente comando:

gcloud container clusters update CLUSTER_NAME \
    --enable-identity-service

Sostituisci CLUSTER_NAME con il nome del tuo cluster.

Configura il servizio di identità per GKE

Puoi configurare i parametri del servizio di identità per GKE scaricando e modificando ClientConfig default.

1. Scarica il ClientConfig default:

   kubectl get clientconfig default -n kube-public -o yaml > client-config.yaml
   

2. Aggiorna la sezione spec.authentication con le impostazioni che preferisci:

   apiVersion: authentication.gke.io/v2alpha1
   kind: ClientConfig
   metadata:
     name: default
     namespace: kube-public
   spec:
     name: cluster-name
     server: https://192.168.0.1:6443
     authentication:
     - name: oidc
       oidc:
         clientID: CLIENT_ID
         certificateAuthorityData: OIDC_PROVIDER_CERTIFICATE
         extraParams: EXTRA_PARAMS
         issuerURI:  ISSUER_URI
         cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
         kubectlRedirectURI: KUBECTL_REDIRECT_URL
         scopes: SCOPES
         userClaim: USER
         groupsClaim: GROUPS
         userPrefix: USER_PREFIX
         groupPrefix: GROUP_PREFIX
   

   Sostituisci quanto segue:

   • CLIENT_ID: l'ID dell'applicazione client che effettua richieste di autenticazione al provider OIDC.
   • OIDC_PROVIDER_CERTIFICATE: (facoltativo) un certificato PEM per il provider OIDC. Questo campo potrebbe essere utile se il tuo provider OIDC utilizza certificati autofirmati. Identity Service per GKE include un insieme di root pubbliche per impostazione predefinita.
   • EXTRA_PARAMS: parametri coppia chiave-valore aggiuntivi da inviare al provider OIDC.
     • Per autorizzare i gruppi, utilizza resource=token-groups-claim.
     • Per autenticare Microsoft Azure e Okta, utilizza prompt=consent.
     • Per Cloud Identity, utilizza prompt=consent,access_type=offline.
   • ISSUER_URI: l'URL a cui inviare le richieste di autorizzazione OIDC, ad esempio https://example.com/adfs. Il server API Kubernetes utilizza questo URL per rilevare le chiavi pubbliche per la verifica dei token. L'URI deve utilizzare HTTPS. Per Cloud Identity, utilizza https://accounts.google.com.
   • KUBECTL_REDIRECT_URL: l'URL di reindirizzamento utilizzato da kubectl oidc login per l'autorizzazione. In genere, il formato è http://localhost:PORT/callback, dove PORT è una porta maggiore di 1024 che sarà disponibile sulle workstation degli sviluppatori, ad esempio http://localhost:10000/callback. Devi registrare l'URL presso il tuo provider OIDC come URL di reindirizzamento autorizzato per l'applicazione client. Se utilizzi Google Identity come provider OIDC, leggi Imposta un URI di reindirizzamento per istruzioni.
   • SCOPES: gli ambiti aggiuntivi da inviare al provider OIDC.
     • Microsoft Azure e Okta richiedono l'ambito offline_access.
     • Per Cloud Identity, utilizza openid, email per ottenere token ID che contengono l'indirizzo email nell'attestazione email.
   • USER: l'attestazione utente dal token di identità.
   • GROUPS: l'attestazione del gruppo dal token di identità.
   • USER_PREFIX: prefisso anteposto alle attestazioni utente per evitare conflitti con i nomi esistenti. Per impostazione predefinita, un prefisso dell'emittente viene aggiunto a userID assegnato al server API Kubernetes (a meno che la rivendicazione dell'utente non sia email). L'identificatore dell'utente risultante è ISSUER_URI#USER. Ti consigliamo di utilizzare un prefisso, ma puoi disattivarlo impostando USER_PREFIX su -.
   • GROUP_PREFIX: prefisso anteposto alle attestazioni dei gruppi per evitare conflitti con i nomi esistenti. Ad esempio, se hai due gruppi denominati foobar, aggiungi un prefisso gid-. Il gruppo risultante è gid-foobar.

3. Applica la configurazione aggiornata:

   kubectl apply -f client-config.yaml
   

   Dopo aver applicato questa configurazione, il servizio di identità per GKE viene eseguito all'interno del cluster e gestisce le richieste dietro il bilanciatore del carico gke-oidc-envoy. L'indirizzo IP nel campo spec.server deve essere l'indirizzo IP del bilanciatore del carico. Se modifichi il campo spec.server, i comandi kubectl potrebbero non riuscire.

4. Crea una copia del file di configurazione client-config.yaml:

   cp client-config.yaml login-config.yaml
   

5. Aggiorna il file di configurazione login-config.yaml con l'impostazione clientSecret nella sezione spec.authentication.oidc.

   clientSecret: CLIENT_SECRET
   

   Sostituisci CLIENT_SECRET con il secret condiviso tra l'applicazione client OIDC e il provider OIDC.

6. Distribuisci il file login-config.yaml aggiornato ai tuoi sviluppatori.

Configura Identity Service for GKE su cluster con policy rigorose

Per configurare il servizio di identità per GKE in modo che funzioni come previsto sui cluster con policy di rete rigorose, segui questi passaggi:

1. Aggiungi una regola firewall per la porta TCP 15000 per consentire al control plane di comunicare con il webhook di convalida ClientConfig.
2. Se gke-oidc-envoy viene creato come bilanciatore del carico interno, esponilo nel VPC.
3. Se hai policy che negano il traffico all'interno del cluster, aggiungi una regola firewall per la porta TCP 8443 per consentire al deployment gke-oidc-envoy di comunicare con il deployment gke-oidc-service.

La versione 0.2.20 e successive del componente Identity Service for GKE non utilizza la porta TCP 15000. Se la versione del componente è 0.2.20 o successiva, non è necessario aggiungere una regola firewall per la porta 15000. Per controllare la versione del componente, esegui questo comando:

kubectl describe deployment gke-oidc-envoy -n anthos-identity-service \
    | grep "components.gke.io/component-name: gke-oidc" -A1

Aggiungi proprietà personalizzate al bilanciatore del carico

Dopo aver configurato il servizio di identità per GKE, puoi aggiungere annotazioni e proprietà personalizzate, ad esempio un indirizzo IP statico, al bilanciatore del carico gke-oidc-envoy. Per modificare il servizio gke-oidc-envoy, esegui questo comando:

kubectl edit service gke-oidc-envoy -n anthos-identity-service

Per saperne di più sulla configurazione del bilanciamento del carico TCP/UDP per GKE, consulta i parametri del servizio LoadBalancer.

Crea una policy RBAC per il cluster

Gli amministratori possono utilizzare il controllo controllo dell'accesso basato su ruoli (RBAC) di Kubernetes per concedere l'accesso agli utenti del cluster autenticati. Per configurare RBAC per il tuo cluster, devi concedere i ruoli RBAC per ogni sviluppatore. Per concedere l'accesso alle risorse in un determinato spazio dei nomi, crea un Role e un RoleBinding. Per concedere l'accesso alle risorse in un intero cluster, crea un ClusterRole e un ClusterRoleBinding.

Ad esempio, considera un utente che deve visualizzare tutti gli oggetti Secret nel cluster. I passaggi seguenti concedono i ruoli RBAC richiesti a questo utente.

1. Salva il seguente manifest ClusterRole come secret-viewer-cluster-role.yaml. Una persona a cui viene concesso questo ruolo può ottenere, controllare ed elencare qualsiasi secret nel cluster.

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: secret-viewer
   rules:
   - apiGroups: [""]
     # The resource type for which access is granted
     resources: ["secrets"]
     # The permissions granted by the ClusterRole
     verbs: ["get", "watch", "list"]
   

2. Applica il manifest ClusterRole:

   kubectl apply -f secret-viewer-cluster-role.yaml
   

3. Salva il seguente manifest ClusterRoleBinding come secret-viewer-cluster-role-binding.yaml. L'associazione concede il ruolo secret-viewer a un nome utente definito nel file di configurazione del client.

   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRoleBinding
   metadata:
     name:  people-who-view-secrets
   subjects:
   - kind: User
     name: ISSUER_URI#USER
     apiGroup: rbac.authorization.k8s.io
   roleRef:
     kind: ClusterRole
     name: secret-viewer
     apiGroup: rbac.authorization.k8s.io
   

   Sostituisci quanto segue:

   • ISSUER_URI: l'URI emittente di spec.authentication.oidc.issuerURI nel file di configurazione del client.
   • USER: l'identificatore dell'utente nel token con il nome della rivendicazione configurato in spec.authentication.oidc.userClaim nel file di configurazione del client.

4. Applica il manifest ClusterRoleBinding:

   kubectl apply -f secret-viewer-cluster-role-binding.yaml
   

Accedi ed esegui l'autenticazione nel cluster

In qualità di sviluppatore che riceve il file di configurazione OIDC dall'amministratore, puoi autenticarti nei tuoi cluster.

1. Scarica il file login-config.yaml fornito dall'amministratore.

2. Installa l'SDK Google Cloud CLI, che offre un componente OIDC separato. Puoi installarlo eseguendo questo comando:

   gcloud components install kubectl-oidc
   

3. Esegui l'autenticazione nel cluster:

   kubectl oidc login --cluster=CLUSTER_NAME --login-config=login-config.yaml
   

   Si apre un browser web per completare la procedura di autenticazione.

4. Dopo l'autenticazione, puoi eseguire i comandi kubectl, ad esempio:

   kubectl get pods
   

Disabilita Identity Service for GKE

Puoi disabilitare Identity Service for GKE con gcloud CLI. Per disabilitare il servizio di identità per GKE, esegui questo comando:

gcloud container clusters update CLUSTER_NAME \
    --no-enable-identity-service

Limitazioni note

Il componente gke-oidc-envoy, responsabile dell'autenticazione nel cluster utilizzando il servizio di identità per GKE, ha un numero fisso di repliche. Ciò significa che non esegue la scalabilità automatica per gestire l'aumento del traffico. Nei cluster regionali, viene eseguito il deployment di questo componente con tre repliche.

Non puoi scalare direttamente il deployment gke-oidc-envoy. Ti consigliamo vivamente di eseguire la migrazione alla federazione delle identità per la forza lavoro per una soluzione scalabile e più solida.

Passaggi successivi

• Scopri di più sulla federazione delle identità per la forza lavoro.
• Scopri di più sul deployment dei workload.