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 supporta OIDC.

Prima di iniziare

  1. Install the 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 del fornitore di cui hai bisogno. Per ulteriori informazioni, vedi Condividere i dettagli del provider di identità.
  6. Per l'autenticazione tramite la console Google Cloud , registra ogni cluster che vuoi configurare nel parco risorse del tuo 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 tua rete VPC attuale 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 tuo parco risorse.

Configura i cluster

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

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

Per ulteriori informazioni sulle informazioni che devi richiedere all'amministratore della piattaforma o alla persona che gestisce l'identità nella tua organizzazione, consulta Condividere i dettagli del provider di identità.

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

Per modificare default ClientConfig, assicurati di poterti connettere al cluster kubectl ed esegui questo comando:

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 ID:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  # 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 autenticarsi con ogni configurazione nell'ordine in cui sono definite e si arresta dopo la prima autenticazione riuscita. L'esempio ClientConfig seguente 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 ClientConfig

La tabella seguente descrive i campi dell'oggetto ClientConfig oidc. I campi che devi aggiungere dipendono dai token del provider di identità e dal modo in cui l'amministratore della piattaforma ha configurato il provider.

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 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 è stato eseguito il deployment di un proxy che consente alla console Google Cloud 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 chiave=valore aggiuntivi da inviare al fornitore 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 da anteporre ai nomi dei gruppi di sicurezza per evitare conflitti con i nomi esistenti nelle regole di controllo dell'accesso#39;accesso se hai configurazioni per più provider di identità (in genere il nome del provider). Stringa
issuerURI Sì L'URI a cui vengono effettuate le richieste di autorizzazione al tuo 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 "nome", 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 da 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 connettersi 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 tuo cluster. Se commetti errori di sintassi, viene visualizzato un messaggio che ti invita a correggerli e a salvare il file.

Configurazioni specifiche del fornitore

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

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'appartenenza di utenti e gruppi da Microsoft Entra ID e di configurare il controllo degli accessi 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 del tenant per gli account che appartengono a un tenant specifico. Il nome del tenant è noto anche come dominio principale. Per informazioni dettagliate su come trovare questi valori, consulta Trovare l'ID tenant Microsoft Entra e il nome di dominio principale.
  • 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 le 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, consulta Configurazione avanzata per Microsoft Entra ID.

Se devi recuperare meno di 200 gruppi per utente, ti consigliamo di utilizzare la configurazione predefinita con 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 massimo di 39 lettere minuscole, numeri o trattini e non può terminare con un trattino.
  • PROXY_URL: l'indirizzo del server proxy da utilizzare per connettersi 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 del tenant per gli account che appartengono a un tenant specifico. Il nome del tenant è noto anche come dominio principale. Per informazioni dettagliate su come trovare questi valori, consulta Trovare l'ID tenant Microsoft Entra e il nome di dominio principale.
  • 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 sul gruppo. Questo campo può assumere 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.
  • (Facoltativo) USER_CLAIM: l'attestazione JWT (nome del campo) utilizzata dal tuo fornitore per identificare un account. Se non specifichi un valore qui, il cluster utilizza un valore nell'ordine "email", "preferred_username" o "sub" per recuperare i dettagli dell'utente. Questo attributo può essere utilizzato a partire 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 rivendicazioni di utenti e gruppi utilizzando un token di accesso e l'endpoint userinfo di Okta.

# 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 al gruppo

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

Passaggi successivi

Una volta applicata la configurazione, continua a configurare l'accesso degli utenti ai cluster.