Configura i cluster membri del parco risorse per l'autenticazione OIDC

Questo documento descrive come gli amministratori dei cluster o gli operatori delle applicazioni possono configurare i cluster per supportare l'autenticazione utilizzando un provider OpenID Connect (OIDC) di terze parti.

Limitazioni

Devi utilizzare un tipo di cluster che supporti OIDC.

Prima di iniziare

1. Installa Google Cloud CLI.

2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

3. Per inizializzare gcloud CLI, esegui questo comando:

   gcloud init

4. Dopo aver inizializzato gcloud CLI, aggiornala e installa i componenti richiesti:

   gcloud components update
   gcloud components install kubectl

5. Assicurati che l'amministratore della piattaforma ti abbia fornito tutte le informazioni sul provider di cui hai bisogno. Per ulteriori informazioni, vedi Condividere i dettagli del provider di identità.
6. Per eseguire l'autenticazione utilizzando la Google Cloud console, registra ogni cluster che vuoi configurare nel parco risorse del progetto. Per ulteriori informazioni, vedi Panoramica della creazione del parco risorse.
7. Per connetterti al control plane di un cluster AWS o Azure che si trova al di fuori della rete VPC corrente tramite un bastion host, assicurati di aver creato il bastion host e di aver avviato un tunnel SSH sulla porta 8118. Quando esegui i comandi kubectl in questo documento, anteponi ai comandi HTTPS_PROXY=http://localhost:PORT, dove PORT è il numero di porta che hai utilizzato quando hai avviato il tunnel SSH.
8. Per i cluster GKE su Google Cloud, registra i cluster nel parco risorse.

Configura i cluster

Per configurare l'autenticazione a un cluster utilizzando OIDC, aggiungi le seguenti informazioni a una risorsa personalizzata Kubernetes denominata ClientConfig:

• Informazioni sul provider di identità, come un ID client e un secret.
• Informazioni sui token web JSON (JWT) utilizzati dal provider di identità per l'autenticazione.
• Eventuali ambiti o parametri aggiuntivi univoci per il provider di identità.

Per ulteriori informazioni sulle informazioni di cui hai bisogno dall'amministratore della piattaforma o da chiunque gestisca l'identità nella tua organizzazione, vedi Condividere i dettagli del provider di identità.

Il cluster utilizza i campi della risorsa personalizzata ClientConfig per interagire con il provider di identità. Ogni cluster ha un ClientConfig denominato default nello spazio dei nomi kube-public. I campi specifici che modifichi dipendono dal provider di identità.

Per modificare il ClientConfig default, assicurati di poter connetterti al cluster kubectl, quindi esegui il comando seguente:

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

Sostituisci KUBECONFIG_PATH con il percorso del file kubeconfig del cluster, ad esempio $HOME/.kube/config.

Un editor di testo carica la risorsa ClientConfig del cluster. Aggiungi l'oggetto spec.authentication.oidc come mostrato nell'esempio seguente. Non modificare i dati predefiniti già scritti.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL
# Rest of the resource is managed by Google. DO NOT MODIFY.

Ad esempio, considera i seguenti campi del token di identità:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['[e-mail]', '[e-mail]']
  # Multiple lines are omitted here
}

In questo esempio, iss è l'URI del provider di identità, sub identifica l'utente e groupList elenca i gruppi di sicurezza a cui appartiene l'utente. Questo esempio mostra solo un campione dei campi che il token effettivo potrebbe avere.

Per il token di esempio precedente, aggiorna i seguenti campi nell'oggetto spec.authentication.oidc di ClientConfig:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

Puoi aggiungere più configurazioni di provider di identità OIDC, LDAP e SAML allo stesso ClientConfig. Il cluster tenta di eseguire l'autenticazione con ogni configurazione nell'ordine in cui sono definite e si interrompe dopo la prima autenticazione riuscita. L'esempio seguente di ClientConfig definisce più provider di identità in un ordine specifico:

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

Campi OIDC di ClientConfig

La tabella seguente descrive i campi dell'oggetto oidc di ClientConfig. I campi che devi aggiungere dipendono dai token del provider di identità e dalla modalità di configurazione del provider da parte dell'amministratore della piattaforma.

Campo	Obbligatorio	Descrizione	Formato
nome	sì	Il nome che vuoi utilizzare per identificare questa configurazione, in genere il nome del provider di identità. Il nome di una configurazione deve iniziare con una lettera seguita da un numero massimo di 39 lettere minuscole, numeri o trattini e non può terminare con un trattino.	Stringa
certificateAuthorityData	No	Se fornita dall'amministratore della piattaforma, una stringa di certificato con codifica PEM per il provider di identità. Includi la stringa risultante in certificateAuthorityData come riga singola.	Stringa
clientID	Sì	L'ID client del provider di identità.	Stringa
clientSecret	No	Secret condiviso tra l'applicazione client OIDC e il provider OIDC.	Stringa
deployCloudConsoleProxy	No	Specifica se viene eseguito il deployment di un proxy che consente alla Google Cloud console di connettersi a un provider di identità on-premise non accessibile pubblicamente su internet. Per impostazione predefinita, questo valore è impostato su false.	Booleano
extraParams	No	Parametri aggiuntivi key=value da inviare al provider di identità, specificati come elenco separato da virgole, ad esempio `prompt=consent,access_type=offline`.	Elenco delimitato da virgole
groupsClaim	No	L'attestazione JWT (nome del campo) utilizzata dal provider per restituire i gruppi di sicurezza di un account.	Stringa
groupPrefix	No	Il prefisso che vuoi anteporre ai nomi dei gruppi di sicurezza per evitare conflitti con i nomi esistenti nelle regole di controllo dell'accesso se hai configurazioni per più provider di identità (in genere il nome del provider).	Stringa
issuerURI	Sì	L'URI in cui vengono effettuate le richieste di autorizzazione al provider di identità. L'URI deve utilizzare HTTPS e non deve terminare con una barra finale.	Stringa URL
kubectlRedirectURI	Sì	L'URL di reindirizzamento e la porta utilizzati da gcloud CLI e specificati dall'amministratore della piattaforma al momento della registrazione, in genere nel formato http://localhost:PORT/callback.	Stringa URL
ambiti	Sì	Ambiti aggiuntivi da inviare al provider OpenID. Ad esempio, Microsoft Azure e Okta richiedono l'ambito offline_access.	Elenco delimitato da virgole
userClaim	No	L'attestazione JWT (nome del campo) utilizzata dal provider per identificare un account utente. Se non specifichi un valore qui, il valore predefinito è "sub", ovvero l'attestazione dell'ID utente utilizzata da molti provider. Puoi scegliere altre attestazioni, ad esempio "email" o "name", a seconda del provider OpenID. Alle attestazioni diverse da "email" viene aggiunto come prefisso l'URL dell'emittente per evitare conflitti di denominazione.	Stringa
userPrefix	No	Il prefisso che vuoi anteporre alle attestazioni utente per evitare conflitti con i nomi esistenti, se non vuoi utilizzare il prefisso predefinito.	Stringa
enableAccessToken	No	Se abilitato, il cluster può utilizzare l'endpoint userinfo del provider di identità per ottenere informazioni sui gruppi quando un utente accede dalla riga di comando. Ciò ti consente di utilizzare i gruppi di sicurezza per l'autorizzazione se hai un provider (come Okta) che fornisce rivendicazioni di gruppi da questo endpoint. Se non è impostato, viene considerato false.	Booleano
proxy	No	Indirizzo del server proxy da utilizzare per la connessione al provider di identità, se applicabile. Potresti dover impostare questo valore se, ad esempio, il cluster si trova in una rete privata e deve connettersi a un provider di identità pubblico. Ad esempio: http://user:password@10.10.10.10:8888.	Stringa

Dopo aver modificato ClientConfig, salva il file per aggiornare ClientConfig per il cluster. Se commetti errori di sintassi, ti viene chiesto di correggerli e salvare il file.

Configurazioni specifiche del provider

Questa sezione fornisce indicazioni sulla configurazione per alcuni provider OIDC più diffusi, incluse configurazioni di esempio che puoi copiare e modificare con i tuoi dati.

Attenzione: devi utilizzare il metodo OIDC standard o Microsoft Entra ID (avanzato). Non applicare entrambi. Queste configurazioni si escludono a vicenda. Se tenti di utilizzare entrambi contemporaneamente, il plug-in OIDC standard sostituisce il plug-in Microsoft Entra ID (avanzato), il che comporta errori di autenticazione per gli utenti con più di 200 appartenenze a gruppi.

Microsoft Entra ID

Questa è la configurazione predefinita per configurare un cluster per l'autenticazione con Microsoft Entra ID. L'utilizzo di questa configurazione consente al cluster di ottenere informazioni sull'iscrizione a utenti e gruppi da Microsoft Entra ID e di configurare il controllo dell'accesso basato sui ruoli (RBAC) di Kubernetes in base ai gruppi. Tuttavia, l'utilizzo di questa configurazione ti consente di recuperare circa 200 gruppi per utente.

Se devi recuperare più di 200 gruppi per utente, consulta le istruzioni per Microsoft Entra ID (avanzato).

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

Sostituisci quanto segue:

• CLIENT_ID: l'ID client di Microsoft Entra ID.
• CLIENT_SECRET: secret condiviso tra l'applicazione client OIDC e il provider OIDC.
• TENANT_ID: il tipo di account Microsoft Entra ID da autenticare. I valori supportati sono l'ID tenant o il nome tenant per gli account che appartengono a un tenant specifico. Il nome tenant è noto anche come dominio principale. Per informazioni dettagliate su come trovare questi valori, vedi Trovare l'ID tenant e il nome di dominio principale di Microsoft Entra.
• PORT: il numero di porta scelto per l'URL di reindirizzamento utilizzato da gcloud CLI, specificato dall'amministratore della piattaforma al momento della registrazione.

Microsoft Entra ID (avanzato)

Questa configurazione facoltativa per Microsoft Entra ID consente al cluster di recuperare informazioni su utenti e gruppi senza limiti al numero di gruppi per utente, utilizzando l'API Microsoft Graph.

Per informazioni sulle piattaforme che supportano questa configurazione, vedi Configurazione avanzata per Microsoft Entra ID.

Se devi recuperare meno di 200 gruppi per utente, ti consigliamo di utilizzare la configurazione predefinita utilizzando un ancoraggio oidc in ClientConfig. Per ulteriori informazioni, consulta le istruzioni per Microsoft Entra ID.

Tutti i campi nella seguente configurazione di esempio sono obbligatori.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM
# Multiple lines are omitted here. Do not modify any pre-filled data.

Sostituisci quanto segue:

• NAME: il nome che vuoi utilizzare per identificare questa configurazione, in genere il nome del provider di identità. Il nome di una configurazione deve iniziare con una lettera seguita da un numero massimo di 39 lettere minuscole, numeri o trattini e non può terminare con un trattino.
• PROXY_URL: indirizzo del server proxy da utilizzare per la connessione al provider di identità, se applicabile. Potresti dover impostare questo valore se, ad esempio, il cluster si trova in una rete privata e deve connettersi a un provider di identità pubblico. Ad esempio: http://user:password@10.10.10.10:8888.
• CLIENT_ID: l'ID client di Microsoft Entra ID.
• CLIENT_SECRET: secret condiviso tra l'applicazione client OIDC e il provider OIDC.
• TENANT: il tipo di account Microsoft Entra da autenticare. I valori supportati sono l'ID tenant o il nome tenant per gli account che appartengono a un tenant specifico. Il nome tenant è noto anche come dominio principale. Per informazioni dettagliate su come trovare questi valori, vedi Trovare l'ID tenant e il nome di dominio principale di Microsoft Entra.
• PORT: il numero di porta scelto per l'URL di reindirizzamento utilizzato da gcloud CLI, specificato dall'amministratore della piattaforma al momento della registrazione.
• GROUP_FORMAT: il formato in cui vuoi recuperare le informazioni sui gruppi. Questo campo può accettare valori corrispondenti a ID o NAME dei gruppi di utenti. Tieni presente che questa impostazione è disponibile solo per i cluster nelle implementazioni di Google Distributed Cloud Bare Metal.
• USER_CLAIM (facoltativo): l'attestazione JWT (nome del campo) utilizzata dal provider per identificare un account. Se non specifichi un valore qui, il cluster utilizza un valore nell'ordine di "email", "preferred_username" o "sub" per recuperare i dettagli dell'utente. Questo attributo può essere utilizzato dalla versione 1.28.

Okta

Di seguito viene illustrato come configurare l'autenticazione utilizzando sia utenti che gruppi con Okta come provider di identità. Questa configurazione consente al cluster di recuperare le attestazioni di utenti e gruppi utilizzando un token di accesso e l'endpoint userinfo di Okta.

Nota: anche se questa configurazione è per Okta, puoi anche recuperare informazioni su utenti e gruppi da qualsiasi altro provider di identità che supporti un endpoint userinfo. Nella configurazione, specifica enableAccessToken: true per utilizzare questa funzionalità.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

Limiti di accesso ai gruppi

Per gli utenti Okta, il cluster può recuperare informazioni sui gruppi per gli utenti i cui nomi di gruppo, se concatenati, hanno una lunghezza inferiore a 170.000 caratteri. Ciò corrisponde a un'appartenenza di circa 650 gruppi, data la lunghezza massima del gruppo di Okta. Se l'utente appartiene a troppi gruppi, la chiamata di autenticazione non riesce.

Passaggi successivi

Dopo aver applicato la configurazione, continua a configurare l'accesso degli utenti ai cluster.