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 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's 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 Kubectl per OIDC, 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.

Scelta di un provider OpenID

Questa sezione è rivolta agli amministratori.

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.

Download del plug-in Kubectl per OIDC

Questa sezione è rivolta agli amministratori e ai dipendenti che vogliono utilizzare il plug-in Kuectl per OIDC.

Scarica il plug-in e imposta le autorizzazioni di accesso:

Linux

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/linux_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Windows

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/windows_amd64/kubectl-oidc .

macOS

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/darwin_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Installare il plug-in

Installa il plug-in spostando il file eseguibile in qualsiasi percorso su PATH. Il file eseguibile deve essere denominato kubectl-oidc. Per scoprire di più, consulta Installazione dei plug-in kubectl.

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

Questa sezione è rivolta agli amministratori.

Per stabilire una relazione con il provider OpenID, devi specificare un URL di reindirizzamento che il provider può utilizzare per restituire i token ID al plug-in Kubectl per OIDC. Il plug-in Kubectl per OIDC viene eseguito sulla macchina locale di ciascun dipendente 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.

Oltre all'URL di reindirizzamento per kubectl, devi utilizzare 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.

Prima che i dipendenti possano utilizzare il plug-in Kubectl per OIDC 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. È qui che il plug-in Kubectl per OIDC o Google Cloud Console invia richieste di autenticazione.

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

  • 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 Kubectl per OIDC che Google Cloud Console.

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

  • Definisci un ambito personalizzato che il plug-in Kubectl per OIDC 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 è destinata ai dipendenti che vogliono creare un cluster configurato per l'utilizzo dell'OIDC.

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:
  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 il plug-in Kubectl per OIDC e la console Google Cloud, 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.
  • clientid: obbligatorio. ID dell'applicazione client che invia le richieste di autenticazione al provider OpenID. Sia il plug-in Kubectl per OIDC che Google Cloud Console utilizzano questo ID.
  • clientsecret: facoltativo. Secret per l'applicazione client. Sia il plug-in Kubectl per OIDC che Google Cloud Console utilizzano questo secret.
  • 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.
  • scopes: facoltativo. Ambiti aggiuntivi da inviare al provider OpenID come elenco delimitato da virgole.
  • 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 all'agente Connect di accedere al provider OIDC on-premise per l'autenticazione degli utenti. Il valore deve essere una stringa: "true" o "false".
  • 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.

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

Salvataggio del certificato dell'autorità di certificazione del server API Kubernetes

Questa sezione è dedicata ai dipendenti che hanno creato un cluster utente e ora vogliono utilizzare il plug-in Kubectl per OIDC.

Il cluster utente ha un server API Kubernetes. Il tuo file kubeconfig del cluster utente archivia il certificato dell'autorità di certificazione che ha emesso un certificato al server API Kubernetes. Il certificato CA è il valore codificato in base-64 del campo certificate-authority-data. Devi decodificare questo valore e archiviarlo in un file locale, ad esempio server-ca-cert:

cat [USER_CLUSTER_KUBECONFIG]  | grep certificate-authority-data | awk '{ print $2}' | base64 --decode > server-ca-cert

Generazione del file di configurazione dell'autenticazione client

Questa sezione è dedicata ai dipendenti che hanno creato un cluster utente e ora vogliono utilizzare il plug-in Kubectl per OIDC.

Per generare un file di configurazione dell'autenticazione client, inserisci il comando seguente:

Linux

kubectl oidc client-config \
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URL] \
--client-id [CLIENT_ID] \
--client-secret [CLIENT_SECRET] \
--scopes "[CUSTOM_SCOPES]" \
--cluster-name [USER_CLUSTER_NAME] \
--server [CLUSTER_URL] \
--server-ca-file [SERVER_CA_CERT] \
--issuer-ca-file [PROVIDER_CA_CERT] \
--extra-params [KEY]=[VALUE], ... # e.g. --extra-params "resource=token-groups-claim"
> client-config.yaml

dove:

  • [ISSUER_URI] è l'URI dell'emittente.
  • [REDIRECT_URL] è l'URL di reindirizzamento per il plug-in Kubectl per OIDC
  • [CLIENT_ID] è l'ID client per il plug-in Kubectl per OIDC.
  • [CLIENT_SECRET] è il client secret del plug-in Kubectl per OIDC.
  • [USER_CLUSTER_NAME] è il nome del cluster utente.
  • [CLUSTER_URL] è l'URL del server API Kubernetes del cluster utente.
  • [SERVER_CA_FILE] è il percorso del certificato dell'autorità di certificazione che ha emesso il certificato al server API Kubernetes. Si tratta del file del certificato che hai creato nella sezione precedente.
  • [PROVIDER_CA_CERT] è il percorso del certificato dell'autorità di certificazione che ha firmato il certificato del provider OpenID. È uguale al valore di oidc:cacert nel file di configurazione del cluster.
  • [CUSTOM_SCOPES] è l'elenco separato da virgole dei tuoi ambiti personalizzati per i gruppi di sicurezza. È uguale al valore di oidc:scopes nel file di configurazione del cluster.
  • --extra-params [KEY]=[VALUE], ... è un elenco di coppie chiave-valore delimitate da virgole da includere nelle richieste di autorizzazione al provider OpenID.

PowerShell

kubectl oidc client-config `
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URL] `
--client-id [CLIENT_ID] `
--client-secret [CLIENT_SECRET] `
--scopes "[CUSTOM_SCOPES]" `
--cluster-name [USER_CLUSTER_NAME] `
--server [CLUSTER_URL] `
--server-ca-file [SERVER_CA_CERT] `
--issuer-ca-file [PROVIDER_CA_CERT] `
--extra-params [KEY]=[VALUE]
> client-config.yaml

dove:

  • [ISSUER_URI] è l'URI dell'emittente.
  • [REDIRECT_URL] è l'URL di reindirizzamento per il plug-in Kubectl per OIDC
  • [CLIENT_ID] è l'ID client per il plug-in Kubectl per OIDC.
  • [CLIENT_SECRET] è il client secret del plug-in Kubectl per OIDC.
  • [USER_CLUSTER_NAME] è il nome del cluster utente.
  • [CLUSTER_URL] è l'URL del server API Kubernetes del cluster utente.
  • [SERVER_CA_FILE] è il percorso del certificato dell'autorità di certificazione che ha emesso il certificato al server API Kubernetes. Si tratta del file del certificato che hai creato nella sezione precedente.
  • [PROVIDER_CA_CERT] è il percorso del certificato dell'autorità di certificazione che ha firmato il certificato del provider OpenID. È uguale al valore di oidc:cacert nel file di configurazione del cluster.
  • [CUSTOM_SCOPES] è l'elenco separato da virgole dei tuoi ambiti personalizzati per i gruppi di sicurezza. È uguale al valore di oidc:scopes nel file di configurazione del cluster.
  • --extra-params [KEY]=[VALUE], ... è un elenco di coppie chiave-valore delimitate da virgole da includere nelle richieste di autorizzazione al provider OpenID.

Questo comando produce un file di configurazione dell'autenticazione client denominato client-config.yaml. Non modificare manualmente questo file.

Autenticazione su un cluster utente utilizzando il plug-in Kubectl per OIDC

Questa sezione è dedicata ai dipendenti che hanno creato un cluster utente e ora vogliono utilizzare il plug-in Kubectl per OIDC.

  1. Inizializza il plug-in usando il file client-config.yaml:

    kubectl oidc login --clientconfig-file=client-config.yaml --user [NAME] \
    --kubeconfig [KUBECONFIG_OUTPUT_PATH]

    dove:

    • [NAME] è il tuo nome utente.
    • [KUBECONFIG_OUTPUT_PATH] è il percorso del file kubeconfig in cui il plug-in Kubectl per OIDC archivia le credenziali.

    kubectl oidc 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 eseguire l'autenticazione sul server API di Kubernetes sul cluster utente.

    Nota: gli utenti Windows potrebbero dover eseguire il comando come kubectl-oidc.exelogin invece che kubectl oidc login.

  2. Verifica che l'autenticazione sia riuscita eseguendo un qualsiasi comando kubectl. Ad esempio:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Utilizzo di OIDC con Google Cloud Console

Questa sezione è destinata ai dipendenti che hanno creato un cluster utente e ora vogliono utilizzare Google Cloud Console per eseguire l'autenticazione sul cluster.

  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.

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 questo potrebbe essere un account diverso da quello che utilizzi 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.