Autenticazione con OIDC e DFS

Questa pagina mostra come utilizzare OpenID Connect (OIDC) con Active Directory Federation Services (AD FS) per configurare l'autenticazione per i cluster utente GKE On-Prem.

Per una panoramica del flusso di autenticazione, consulta Autenticazione. Per informazioni sull'utilizzo di provider OpenID diversi da AD FS, consulta la pagina relativa all'autenticazione con OpenID Connect.

Panoramica

GKE On-Prem supporta OpenID Connect (OIDC) come uno dei meccanismi di autenticazione per interagire con il server API 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. Puoi utilizzare una serie di procedure guidate di gestione di AD FS per configurare il tuo server AD FS e il tuo database di dipendenti AD.

Prima di iniziare

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

Questo argomento riguarda le aziende che dispongono della seguente infrastruttura:

  • L'azienda utilizza Active Directory (AD) per il suo database di dipendenti.
  • L'azienda esegue un server AD Directory FS (Active Directory Federation Services).
  • Il server AD FS funge da provider OpenID.

Download del plug-in Kubectl per OIDC

Questa sezione è rivolta agli amministratori e ai dipendenti che vogliono utilizzare il plug-in Kubect 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 qualunque percorso del PATH. Il file eseguibile deve essere denominato kubectl-oidc. Per saperne di più, consulta Installare i plug-in kubectl.

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

Questa sezione è rivolta agli amministratori.

Nel stabilire una relazione con il server AD FS, devi specificare un URL di reindirizzamento che il server AD FS 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 sulla porta che preferisci. Scegli un numero di porta superiore a 1024 adatto a questo scopo. L'URL di reindirizzamento è quindi:

http://localhost:[PORT]/callback

dove [PORT] è il tuo numero di porta.

Quando configuri il server AD FS, specifica http://localhost:[PORT]/callback come uno degli URL di reindirizzamento.

Configurare un URL di reindirizzamento per la console Google Cloud

Questa sezione è rivolta agli amministratori.

Oltre ad avere un URL di reindirizzamento per il plug-in Kubectl per OIDC, è necessario un URL di reindirizzamento per la console Google Cloud. L'URL di reindirizzamento per la console Google Cloud è:

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

Quando configuri il server AD FS, specifica https://console.cloud.google.com/kubernetes/oidc come uno degli URL di reindirizzamento.

Configurazione di AD FS

Le sezioni seguenti spiegano come configurare AD FS per GKE On-Prem.

Impostazione degli URL di reindirizzamento

  1. Apri il riquadro di gestione di AD FS.

  2. Seleziona Gruppi di applicazioni > Azioni > Aggiungi un gruppo di applicazioni.

  3. Seleziona Server Application (Applicazione server). Inserisci un nome e una descrizione a tua scelta. Fai clic su Next (Avanti).

  4. Inserisci i tuoi due URL di reindirizzamento. Ti verrà assegnato un ID client. Ecco come il server AD FS identifica il plug-in Kubectl per la console OIDC e Google Cloud. Salva l'ID client per un utilizzo futuro.

  5. Seleziona Genera un secret condiviso. Il plug-in Kubectl per OIDC e Google Cloud Console utilizza questo secret per l'autenticazione nel server AD FS. Salva il segreto per usarlo in un secondo momento.

(Facoltativo) Configurare i gruppi di sicurezza

  1. Nella gestione di AD FS, seleziona Affidabilità parte del gruppo > Aggiungi un nuovo trust del gruppo di attendibilità.

  2. Seleziona Rivendicazioni sensibili e fai clic su Inizia.

  3. Seleziona Inserisci manualmente i dati relativi all'attendibilità del soggetto.

  4. Inserisci un nome visualizzato.

  5. Salta i due passaggi successivi.

  6. Inserisci un identificatore di attendibilità parte. Suggerimento: token-groups-claim.

  7. In Criterio di controllo dell'accesso, seleziona Consenti tutti. Ciò significa che tutti i dipendenti condividono le informazioni sul proprio gruppo di sicurezza con il plug-in Kubectl per OIDC e la console Google Cloud.

  8. Fai clic su Fine.

Mappatura degli attributi LDAP alle denominazioni delle rivendicazioni

  1. Nella gestione di AD FS, seleziona Fiducia delle parti attendibili > Modifica criterio di emissione delle rivendicazioni.

  2. Seleziona Invia attributi LDAP come rivendicazioni, quindi fai clic su Avanti.

  3. In Nome regola rivendicazione, inserisci groups.

  4. In Archivio attributi, seleziona Active Directory.

  5. Nella tabella, per Attributo LDAP, seleziona:

    • AD FS 5.0 e versioni successive: Gruppi di token qualificati per nome di dominio
    • Versioni AD FS precedenti alla 5.0: Gruppi di token - Nomi qualificati

  6. In Tipo di rivendicazione in uscita, seleziona:

    • AD FS 5.0 e versioni successive: gruppo
    • Versioni AD FS precedenti alla 5.0: gruppi

  7. Fai clic su Fine e poi su Applica.

Registrazione del plug-in Kubectl per OIDC e Google Cloud Console con AD FS

Apri una finestra di PowerShell in modalità Amministratore e inserisci questo comando:

Grant-AD FSApplicationPermission `
    -ClientRoleIdentifier "[CLIENT_ID]" `
    -ServerRoleIdentifier [SERVER_ROLE_IDENTIFIER] `
    -ScopeName "allatclaims", "openid"

dove:

  • [CLIENT_ID] è l'ID client ottenuto in precedenza.

  • [SERVER_ROLE_IDENTIFIER] è l'identificatore della rivendicazione inserito in precedenza. Ricorda che l'identificatore suggerito è token-groups-claim.

Completamento della specifica oidc nel file di configurazione del cluster

Questa sezione è dedicata ai dipendenti che vogliono creare un cluster configurato per l'utilizzo di OIDC.

Prima di creare un cluster utente, generi un file di configurazione GKE On-Prem utilizzando gkectl create-config. La configurazione include la seguente specifica oidc. Compila oidc con valori specifici del 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 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 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. L'impostazione predefinita è sub, che dovrebbe essere un identificatore univoco dell'utente finale. Puoi scegliere altre rivendicazioni, come email o name, a seconda del provider OpenID. Tuttavia, le rivendicazioni diverse da email sono precedute dall'URL dell'emittente per evitare conflitti di denominazione con altri plug-in.
  • usernameprefix: facoltativo. Prefisso anteposto alle rivendicazioni dei nomi utente per evitare conflitti con i nomi esistenti. Se non fornisci questo campo e username è un valore diverso da email, il prefisso viene impostato automaticamente su issuerurl#. Puoi utilizzare il valore - per disattivare tutti i prefissi.
  • group: facoltativo. JWT afferma che il provider utilizzerà per restituire i tuoi gruppi di sicurezza.
  • groupprefix: facoltativo. Prefisso anteposto alle rivendicazioni del gruppo 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 delle coppie chiave-valore aggiuntivi da inviare al provider OpenID sotto forma di 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 CA pubblica ben conosciuta, non devi fornire un valore qui.

Esempio: autorizzare utenti e gruppi

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

  • Gli ID utente possono rendere difficili la lettura e l'audit dei criteri.
  • Le email possono creare sia un rischio di disponibilità (se un utente modifica la loro email principale) sia potenzialmente un rischio per la sicurezza (se un'email può essere riassegnata).

Pertanto, è una best practice utilizzare i criteri di gruppo, poiché un ID di gruppo può essere sia persistente sia 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']
  ...
}
Dato questo formato di token, devi inserire le specifiche del tuo file di configurazione oidc in questo modo: 
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 ai suoi utenti l'accesso di sola lettura ai Secret del cluster, quindi 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 della CA del server API Kubernetes in corso...

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

Il cluster utente dispone di un server API Kubernetes. Inoltre, il file kubeconfig del tuo cluster utente archivia il certificato della CA che ha emesso un certificato al server API Kubernetes. Il certificato della CA è il valore codificato in base 64 del campo certificate-authority-data. Devi decodificare questo valore e memorizzarlo 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 questo comando:

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 del plug-in Kubectl per OIDC.
  • [CLIENT_SECRET] è il client secret per il plug-in Kubectl per OIDC.
  • [USER_CLUSTER_NAME] è il nome del tuo cluster utente.
  • [CLUSTER_URL] è l'URL del server API Kubernetes del cluster utente.
  • [SERVER_CA_FILE] è il percorso del certificato della CA che ha emesso un certificato al server API Kubernetes. Questo è il file del certificato che hai creato nella sezione precedente.
  • [PROVIDER_CA_CERT] è il percorso del certificato della CA che ha firmato il certificato del provider OpenID. Corrisponde 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. Corrisponde al valore oidc:scopes nel file di configurazione del cluster.
  • --extra-params [KEY]=[VALUE], ... è un elenco di coppie chiave-valore delimitati 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 del plug-in Kubectl per OIDC.
  • [CLIENT_SECRET] è il client secret per il plug-in Kubectl per OIDC.
  • [USER_CLUSTER_NAME] è il nome del tuo cluster utente.
  • [CLUSTER_URL] è l'URL del server API Kubernetes del cluster utente.
  • [SERVER_CA_FILE] è il percorso del certificato della CA che ha emesso un certificato al server API Kubernetes. Questo è il file del certificato che hai creato nella sezione precedente.
  • [PROVIDER_CA_CERT] è il percorso del certificato della CA che ha firmato il certificato del provider OpenID. Corrisponde 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. Corrisponde al valore oidc:scopes nel file di configurazione del cluster.
  • --extra-params [KEY]=[VALUE], ... è un elenco di coppie chiave-valore delimitati da virgole da includere nelle richieste di autorizzazione al provider OpenID.

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

Autenticazione rispetto a 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 utilizzando 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 l'autenticazione nel server API Kubernetes nel cluster utente.

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

  2. Verifica che l'autenticazione sia andata a buon fine eseguendo qualsiasi comando kubectl. Ad esempio:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Utilizzo di OIDC con la console Google Cloud

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

  1. Verifica che il 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 nella console Google Cloud.

    Visita la pagina Cluster Kubernetes

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

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

    Si aprirà il provider di identità, dove potresti dover accedere o concedere il consenso alla console Google Cloud per accedere al tuo account. Si aprirà quindi la pagina Cluster Kubernetes in Google Cloud Console.

Riepilogo

La tua azienda esegue un server AD FS che funge da provider OpenID. Il tuo provider OpenID conosce le tue due applicazioni client: il plug-in Kubectl per OIDC e la console Google Cloud. Il tuo provider OpenID sa che le applicazioni client possono richiedere gli ambiti openid e allatclaims.

Nella versione AD FS precedente alla 5.0, l'attributo LDAP Token-Groups Qualified Names nel database AD è mappato alla rivendicazione groups nel tuo provider OpenID. Nella versione 5.0 e successive, l'attributo è Token-Groups Qualified by Domain name. Il provider restituisce i token che includono l'ID del dipendente, l'ID dell'emittente, la rivendicazione openid e groups. La rivendicazione groups (Group in 5.0) elenca i gruppi di sicurezza a cui appartiene un dipendente.

Risoluzione dei problemi di OIDC in GKE On-Prem

Configurazione non valida

Se la console Google Cloud non riesce a leggere la configurazione OIDC dal cluster, il pulsante ACCESSO viene disabilitato.

Configurazione del provider non valida

Se la configurazione del provider di identità non è valida, verrà visualizzata una schermata di errore dal provider di identità dopo aver fatto clic su ACCEDI. 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 trattarsi di 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 non è stato fornito il parametro di autenticazione richiesto. Fornisci il parametro prompt=consent al campo oidc: extraparams del file di configurazione di GKE On-Prem e rigenera il file di autenticazione client con il flag --extra-params prompt=consent.

Passaggi successivi