Autenticazione con OpenID Connect (OIDC)

Questa pagina mostra come configurare GKE On-Prem per utilizzare un provider OpenID per l'autenticazione nei cluster utente. Per informazioni su come utilizzare OIDC con AD FS, consulta Autenticarsi con OIDC e AD FS. Per informazioni su come utilizzare OIDC con il provider OpenID di Google, consulta la pagina sull'autenticazione con OIDC e Google.

Per una panoramica del flusso di autenticazione GKE On-Prem, consulta Autenticazione.

Panoramica

GKE On-Prem supporta OpenID Connect (OIDC) come uno dei meccanismi di autenticazione per interagire con un server API Kubernetes di un cluster utente. Con OIDC puoi gestire l'accesso ai cluster Kubernetes utilizzando le procedure standard nella tua organizzazione per creare, abilitare e disabilitare gli account dei dipendenti.

Un dipendente può utilizzare il flusso di autenticazione OIDC in due modi:

  • Un dipendente può utilizzare kubectl per avviare un flusso OIDC. Per rendere questo flusso automatico, GKE On-Prem fornisce il plug-in Anthos per Kubectl, un plug-in kubectl.
  • Un dipendente può utilizzare Google Cloud Console per avviare un flusso di autenticazione OIDC.

In questo esercizio configurerai entrambe le opzioni: kubectl e Google Cloud Console.

Prima di iniziare

Questo argomento presuppone che tu abbia dimestichezza con OAuth 2.0 e OpenID Connect. Questo argomento presuppone che tu abbia dimestichezza con gli ambiti e le rivendicazioni OpenID.

Utenti tipo

Questo argomento si riferisce a tre utenti tipo:

  • Amministratore organizzazione: questa persona sceglie un provider OpenID e registra le applicazioni client con il provider.

  • Amministratore cluster: questa persona crea uno o più cluster utente e crea file di configurazione di autenticazione per gli sviluppatori che utilizzano i cluster.

  • Sviluppatore: questa persona esegue carichi di lavoro su uno o più cluster e utilizza OIDC per l'autenticazione.

Scelta di un provider OpenID

Questa sezione è rivolta agli amministratori dell'organizzazione.

Puoi utilizzare qualsiasi provider OpenID di tua scelta. Per un elenco dei provider certificati, consulta la sezione Certificazione OpenID.

Una possibilità è utilizzare Active Federated Services (AD FS) di Active Directory come provider OpenID e un'istanza on-premise di Active Directory come database dei dipendenti. Per ulteriori informazioni, consulta la pagina relativa all'autenticazione con OIDC e AD FS.

Un'altra possibilità è utilizzare Google come provider OpenID.

Creazione di un URL di reindirizzamento per il plug-in Anthos per Kubectl

Questa sezione è rivolta agli amministratori dell'organizzazione.

Per stabilire una relazione con il provider OpenID, devi specificare un URL di reindirizzamento che il provider può utilizzare per restituire token ID al plug-in Anthos per Kubectl. Il plug-in Anthos per Kubectl viene eseguito su ogni macchina locale dello sviluppatore e rimane in ascolto su una porta a tua scelta. Scegli un numero di porta superiore a 1024 che sia adatto a questo scopo. L'URL di reindirizzamento sarà:

http://localhost:[PORT]/callback

dove [PORT] è il tuo numero di porta.

Quando configuri il tuo provider OpenID, specifica http://localhost:[PORT]/callback come uno degli URL di reindirizzamento. Il modo in cui esegui questa operazione dipende dal provider.

Configurazione di un URL di reindirizzamento per Google Cloud Console

Questa sezione è rivolta agli amministratori dell'organizzazione.

Oltre all'URL di reindirizzamento per kubectl, è necessario un URL di reindirizzamento per Google Cloud Console. L'URL di reindirizzamento per Google Cloud Console è:

https://console.cloud.google.com/kubernetes/oidc

Quando configuri il provider OIDC, specifica https://console.cloud.google.com/kubernetes/oidc come uno degli URL di reindirizzamento. La modalità di calcolo dipende dal provider.

Registrazione delle applicazioni client con il provider OpenID

Questa sezione è rivolta agli amministratori dell'organizzazione.

Prima che gli sviluppatori possano utilizzare la versione plug-in Anthos per Kubectl o Google Cloud Console con il tuo provider OpenID, devi registrare i due client sul provider OpenID. La registrazione prevede questi passaggi:

  • Scopri l'URI dell'emittente del fornitore. A questo punto, il plug-in Anthos per Kubectl o Google Cloud Console invia richieste di autenticazione.

  • Fornisci al provider l'URL di reindirizzamento del plug-in Anthos per Kubectl.

  • Fornisci al provider l'URL di reindirizzamento di Google Cloud Console. Questo è https://console.cloud.google.com/kubernetes/oidc.

  • Stabilisci un singolo ID client. Questo è l'ID utilizzato dal provider per identificare sia il plug-in Anthos per Kubectl che Google Cloud Console.

  • Stabilisci un singolo client secret. Il plug-in Anthos per Kubectl e Google Cloud Console utilizzano entrambi questo secret per autenticarsi al provider OpenID.

  • Definisci un ambito personalizzato che il plug-in Anthos per Kubectl o Google Cloud Console possa utilizzare per richiedere i gruppi di sicurezza degli utenti.

  • Definisci un nome di rivendicazione personalizzato che il provider utilizzerà per restituire i gruppi di sicurezza dell'utente.

Le modalità di esecuzione di questi passaggi dipendono dal provider OpenID. Per informazioni su come eseguire la procedura di registrazione con AD FS, consulta l'articolo sull'autenticazione con OIDC e AD FS.

Completa la specifica oidc nel file di configurazione GKE On-Prem

Questa sezione è rivolta agli amministratori del cluster.

Prima di creare un cluster utente, devi generare un file di configurazione GKE On-Prem utilizzando gkectl create-config. La configurazione include la seguente specifica oidc. In oidc inserisci valori specifici per il tuo provider:

oidc:
  issuerurl:
  kubectlredirecturl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: obbligatorio. URL del tuo provider OpenID, ad esempio "https://example.com/adfs". Le applicazioni client, come Anthos Plugin for Kubectl e Google Cloud Console, inviano le richieste di autorizzazione a questo URL. Il server API di Kubernetes utilizza questo URL per rilevare le chiavi pubbliche per la verifica dei token. È necessario utilizzare HTTPS.
  • kubectlredirecturl: Campo obbligatorio. L'URL di reindirizzamento configurato in precedenza per il plug-in Anthos per Kubectl.
  • clientid: obbligatorio. ID dell'applicazione client che invia le richieste di autenticazione al provider OpenID. Sia il plug-in Anthos per Kubectl sia la console Google Cloud utilizzano questo ID.
  • clientsecret: facoltativo. Secret per l'applicazione client. Questo plug-in viene utilizzato sia dal plug-in Anthos per Kubectl sia da Google Cloud Console.
  • username: facoltativo. Attestazione JWT da utilizzare come nome utente. Il valore predefinito è sub, che dovrebbe essere un identificatore univoco dell'utente finale. Puoi scegliere altre attestazioni, ad esempio email o name, a seconda del provider OpenID. Tuttavia, alle attestazioni diverse da email viene aggiunto come prefisso l'URL dell'emittente per evitare conflitti di denominazione con altri plug-in.
  • usernameprefix: facoltativo. Prefisso anteposto alle attestazioni dei nomi utente per evitare conflitti con i nomi esistenti. Se non specifichi questo campo e username è un valore diverso da email, il valore predefinito del prefisso è issuerurl#. Puoi utilizzare il valore - per disattivare tutti i prefissi.
  • group: facoltativo. Attestazione JWT che il provider utilizzerà per restituire i tuoi gruppi di sicurezza.
  • groupprefix: facoltativo. Prefisso anteposto alle attestazioni dei gruppi per evitare conflitti con i nomi esistenti. Ad esempio, dato un gruppo foobar e un prefisso gid-, gid-foobar. Per impostazione predefinita, il valore è vuoto e non esiste un prefisso.
  • scopes: facoltativo. Ambiti aggiuntivi da inviare al provider OpenID come elenco delimitato da virgole.
    • Per l'autenticazione con Microsoft Azure o Okta, passa il passaggio offline_access.

  • extraparams: facoltativo. Parametri coppia chiave-valore aggiuntivi da inviare al provider OpenID come elenco delimitato da virgole.
  • usehttpproxy: facoltativo. Specifica se eseguire il deployment di un proxy inverso nel cluster per consentire a Google Cloud Console di accedere al provider OIDC on-premise per l'autenticazione degli utenti. Il valore deve essere una stringa: "true" o "false". Se il tuo provider di identità non è raggiungibile sulla rete Internet pubblica e vuoi eseguire l'autenticazione utilizzando Google Cloud Console, questo campo deve essere impostato su "true". Se lasci il campo vuoto, questo campo viene impostato su "false" per impostazione predefinita.

  • capath: facoltativo. Percorso del certificato dell'autorità di certificazione (CA) che ha emesso il certificato web del tuo provider di identità. Questo valore potrebbe non essere necessario. Ad esempio, se il certificato del tuo provider di identità è stato emesso da una nota CA pubblica, non dovrai fornire un valore qui. Tuttavia, se usehttpproxy è "true", questo valore deve essere fornito, anche per una nota CA pubblica.

Esempio: autorizzare utenti e gruppi

Molti provider codificano le proprietà di identificazione degli utenti, come email e User-ID, in un token. Tuttavia, queste proprietà presentano rischi impliciti per i criteri di autenticazione:

  • Gli ID utente possono rendere i criteri difficili da leggere e controllare.
  • Le email possono creare sia un rischio di disponibilità (se un utente cambia l'indirizzo email principale) sia un rischio per la sicurezza (se un'email può essere riassegnata).

Pertanto, è una best practice utilizzare i criteri di gruppo, poiché un ID gruppo può essere sia persistente che più facile da controllare.

Supponiamo che il tuo provider crei token di identità che includano i seguenti campi:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

Considerato il formato del token, dovrai completare la specifica del file di configurazione oidc, ad esempio:

issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

Dopo aver creato il cluster utente, puoi utilizzare il controllo dell'accesso basato sui ruoli (RBAC) di Kubernetes per concedere l'accesso con privilegi agli utenti autenticati. Ad esempio, puoi creare un ClusterRole che conceda agli utenti l'accesso in sola lettura ai secret del cluster e creare una risorsa ClusterRoleBinding per associare il ruolo al gruppo autenticato:

ClusterRole

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

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Creazione del primo file di configurazione dell'autenticazione

Questa sezione è rivolta agli amministratori del cluster.

Dopo aver creato un cluster utente, crea un file di configurazione di autenticazione per il cluster:

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG]

dove [USER_CLUSTER_KUBECONFIG] è il percorso del file kubeconfig del cluster utente. Quando hai creato il cluster utente, gkectl create cluster ha generato un file kubeconfig per il cluster.

Il comando precedente crea un file denominato kubectl-anthos-config.yaml nella directory corrente.

Aggiunta di cluster aggiuntivi al file di configurazione dell'autenticazione

Questa sezione è rivolta agli amministratori del cluster.

Puoi archiviare la configurazione di autenticazione per più cluster in un unico file. Quindi puoi distribuire quel file agli sviluppatori che hanno bisogno di accedere a tutti questi cluster.

Inizia con un file di configurazione dell'autenticazione esistente. Quindi usa il comando seguente per unire quel file alla configurazione di un cluster aggiuntivo:

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG] \
    --merge-from [IN_AUTH_CONFIG_FILE] --output [OUT_AUTH_CONFIG_FILE]

dove

  • [USER_CLUSTER_KUBECONFIG] è il file kubeconfig del cluster aggiuntivo.

  • [IN_AUTH_CONFIG_FILE] è il percorso del file di configurazione dell'autenticazione esistente.

  • [OUT_AUTH_CONFIG_FILE] è il percorso in cui vuoi salvare il file contenente la configurazione unita. Può essere uguale a [IN_AUTH_CONFIG_FILE].

Distribuzione del file di configurazione dell'autenticazione

Questa sezione è rivolta agli amministratori del cluster.

Il nome del file di configurazione dell'autenticazione che distribuisci agli sviluppatori deve essere kubectl-anthos-config.yaml. Puoi distribuire il file di configurazione dell'autenticazione in diversi modi:

  • Fornisci manualmente il file a ogni sviluppatore.

  • Ospita il file a un URL, in modo che gli sviluppatori possano scaricarlo.

  • Esegui il push del file sul computer di ogni sviluppatore.

Indipendentemente dal metodo di distribuzione, per una configurazione predefinita, il file di configurazione di autenticazione deve essere posizionato in questa posizione su ogni computer dello sviluppatore:

Linux

$HOME/.config/google/anthos/kubectl-anthos-config.yaml

macOS

$HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

Windows

%APPDATA%\google\anthos\kubectl-anthos-config.yaml

Se non vuoi utilizzare la configurazione predefinita, puoi creare una configurazione personalizzata.

Inserimento del file di configurazione dell'autenticazione

Questa sezione è rivolta agli sviluppatori.

Il file di configurazione dell'autenticazione contiene i dettagli di tutti i cluster in cui è possibile eseguire l'autenticazione. Non modificare i contenuti di questo file.

Se l'amministratore del cluster ti ha fornito un file di configurazione dell'autenticazione, inseriscilo nella directory corretta. Se l'amministratore del tuo cluster ha già posizionato la configurazione sulla macchina, puoi saltare questa sezione.

Copia il file di configurazione dell'autenticazione nella posizione predefinita:

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

dove [AUTH_CONFIG_FILE] è il nome del tuo file di configurazione dell'autenticazione.

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

dove [AUTH_CONFIG_FILE] è il nome del tuo file di configurazione dell'autenticazione.

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

dove [AUTH_CONFIG_FILE] è il nome del tuo file di configurazione dell'autenticazione.

Scaricare il plug-in Anthos per Kubectl

Questa sezione è rivolta agli amministratori del cluster.

Il plug-in Anthos per Kubectl è incluso nella workstation di amministrazione all'indirizzo:

Linux

/usr/bin/kubectl_anthos/v1.0beta/linux_amd64/kubectl-anthos

macOS

/usr/bin/kubectl_anthos/v1.0beta/darwin_amd64/kubectl-anthos

Windows

/usr/bin/kubectl_anthos/v1.0beta/windows_amd64/kubectl-anthos

Puoi distribuire il plug-in agli sviluppatori o farli scaricare direttamente.

Download del plug-in Anthos per Kubectl

Questa sezione è rivolta agli amministratori e agli sviluppatori dei cluster.

Ogni sviluppatore deve avere il plug-in Anthos per Kubectl sulla propria macchina. Gli sviluppatori possono scaricare il plug-in singolarmente o l'amministratore del cluster può scaricarlo e poi distribuirlo agli sviluppatori.

Nota per gli sviluppatori: chiedi all'amministratore del cluster quale versione del plug-in dovresti utilizzare.

Scarica il plug-in Anthos per Kubectl:

Linux

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/linux_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

macOS

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/darwin_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

Windows

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/windows_amd64/kubectl-anthos ./
rename kubectl-anthos kubectl-anthos.exe.

Installazione del plug-in Anthos per Kubectl

Questa sezione è rivolta agli sviluppatori.

L'amministratore del tuo cluster potrebbe fornirti il plug-in Anthos per Kubectl. In alternativa, l'amministratore del tuo cluster potrebbe chiederti di scaricare il plug-in autonomamente.

Per installare il plug-in Anthos per Kubectl, sposta il file eseguibile in qualsiasi percorso del percorso PATH. Per Linux e macOS, il file eseguibile deve essere denominato kubectl-anthos. Nel caso di Windows, deve essere denominato kubectl-anthos.exe. Per saperne di più, consulta la pagina relativa all'installazione dei plug-in kubectl.

Verifica che il plug-in Anthos per Kubectl sia installato:

kubectl plugin list
kubectl anthos version

Elenco dei cluster disponibili

Questa sezione è rivolta agli sviluppatori.

Se il percorso di configurazione del file di autenticazione è predefinito, inserisci questo comando per elencare i cluster su cui puoi eseguire l'autenticazione:

kubectl anthos listclusters

Se il file di configurazione di autenticazione non si trova nel percorso predefinito, inserisci questo comando per elencare i cluster:

kubectl anthos listclusters --loginconfig [AUTH_CONFIG_FILE]

dove [AUTH_CONFIG_FILE] è il percorso del file di configurazione dell'autenticazione.

Utilizzo del plug-in Anthos per Kubectl per l'autenticazione

Questa sezione è rivolta agli sviluppatori.

Accedi a un cluster utente:

kubectl anthos login --cluster [CLUSTER_NAME] --user [USER_NAME] \
     --loginconfig [AUTH_CONFIG_FILE] --kubeconfig [USER_CLUSTER_KUBECONFIG]

dove:

  • [CLUSTER_NAME] è il nome del cluster utente. Questo nome deve essere selezionato dall'elenco fornito dal comando kubectl anthos listclusters.

  • [USER_NAME] un parametro facoltativo che specifica il nome utente per le credenziali memorizzate nel file kubeconfig. Il valore predefinito è [CLUSTER_NAME]-anthos-default-user.

  • [AUTH_CONFIG_FILE] è il percorso del file di configurazione dell'autenticazione. Se il file di configurazione dell'autenticazione si trova nella località predefinita, puoi omettere questo parametro.

  • [USER_CLUSTER_KUBECONFIG] è il percorso del file kubeconfig del cluster utente. Se un file kubeconfig non esiste, il comando genera un nuovo file kubeconfig dal file di configurazione di autenticazione e aggiunge i dettagli e i token del cluster al file kubeconfig.

kubectl anthos login avvia un browser in cui puoi inserire le tue credenziali.

Il file kubeconfig fornito ora contiene un token ID che kubectl può utilizzare per autenticarsi sul server API Kubernetes sul cluster utente.

Il comando kubectl anthos login ha un flag --dry-run facoltativo. Se includi il flag --dry-run, il comando stampa i comandi kubectl che aggiungerebbero token al file kubeconfig, ma in realtà non li salva nel file kubeconfig.

Per verificare che l'autenticazione sia riuscita, inserisci un comando kubectl. Ad esempio:

kubectl get nodes --kubeconfig [USER_CLUSTER_KUBECONFIG]

Utilizzo di OIDC con Google Cloud Console

Questa sezione è rivolta agli sviluppatori.

  1. Verifica che il tuo cluster sia configurato per OIDC.

  2. Verifica che il cluster sia stato registrato con Google Cloud, automaticamente durante la creazione del cluster o manualmente.

  3. Visita la pagina Cluster Kubernetes in Google Cloud Console.

    Visita la pagina Cluster Kubernetes

  4. Nell'elenco dei cluster, individua il cluster GKE On-Prem e fai clic su Accedi.

  5. Seleziona Autentica con il provider di identità configurato per il cluster e fai clic su ACCESSO.

    Si aprirà il provider di identità, dove potresti dover accedere o dare il tuo consenso affinché Google Cloud Console acceda al tuo account. Quindi verrai reindirizzato alla pagina Cluster Kubernetes in Google Cloud Console.

Configurazione personalizzata

Per impostazione predefinita, il plug-in Anthos per Kubectl prevede che il file di configurazione dell'autenticazione si trovi in una determinata posizione. Se non vuoi mettere il file di configurazione dell'autenticazione nella posizione predefinita, puoi passare manualmente il percorso del file di configurazione dell'autenticazione ai comandi del plug-in utilizzando il flag --login-config. Ad esempio, consulta la pagina relativa all'uso del plug-in Anthos per Kubectl per l'autenticazione.

Risoluzione dei problemi OIDC in GKE On-Prem

Configurazione non valida

Se Google Cloud Console non riesce a leggere la configurazione OIDC dal cluster, il pulsante ACCESSO verrà disabilitato.

Configurazione del provider non valida

Se la configurazione del tuo provider di identità non è valida, verrà visualizzata una schermata di errore del provider di identità dopo aver fatto clic su ACCESSO. Segui le istruzioni specifiche del provider per configurare correttamente il provider o il cluster.

Autorizzazioni non valide

Se completi il flusso di autenticazione, ma continui a non vedere i dettagli del cluster, assicurati di aver concesso le autorizzazioni RBAC corrette all'account che hai utilizzato con OIDC. Tieni presente che potrebbe essere un account diverso da quello che usi per accedere a Google Cloud Console.

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

Potresti visualizzare questo errore se il server di autorizzazione richiede il consenso, ma il parametro di autenticazione richiesto non è stato fornito. Fornisci il parametro prompt=consent al campo oidc: extraparams del file di configurazione GKE on-prem e rigenera il file di autenticazione client con il flag --extra-params prompt=consent.