Risolvere i problemi di autenticazione di terze parti con un'utilità di diagnostica

Puoi utilizzare un'utilità di diagnostica per risolvere i problemi di autenticazione basata su FQDN nei cluster membri del parco risorse. Se riscontri difficoltà durante l'autenticazione a un cluster utilizzando un provider OIDC specifico, puoi attivare lo strumento e utilizzarlo per identificare rapidamente i problemi di configurazione simulando i flussi di accesso con il tuo provider OIDC. Questo documento si applica solo ai tipi di cluster supportati.

L'utilità di diagnostica è disponibile solo sui singoli cluster che eseguono la versione 1.32 o successive e supporta solo OIDC.

Attivare l'utilità di diagnostica

L'utilità di diagnostica è disattivata per impostazione predefinita e deve essere attivata prima di poterla utilizzare per la risoluzione dei problemi. Per attivarla, segui queste istruzioni:

  1. Apri la risorsa personalizzata ClientConfig per la modifica:

    kubectl edit clientconfig default \
    --kubeconfig CLUSTER_KUBECONFIG -n kube-public

    Il manifest dovrebbe essere simile al seguente:

    apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: oidc
    oidc:
      clientID: example-client-id
      clientSecret: example-client-secret
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://example.com
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

  2. Come mostrato nell'esempio seguente, aggiungi una sezione identityServiceOptions al manifest ClientConfig per specificare la configurazione dell'utilità di diagnostica:

    apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
  metadata:
    name: default
    namespace: kube-public
  spec:
    identityServiceOptions:
      diagnosticInterface:
        enabled: true
        expirationTime: TIMESTAMP
    authentication:
    - name: oidc
      oidc:
        clientID: example-client-id
        clientSecret: example-client-secret
        cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
        extraParams: prompt=consent, access_type=offline
        issuerURI: https://example.com
        kubectlRedirectURI: http://localhost:PORT/callback
        scopes: openid,email,offline_access
        userClaim: email

    Sostituisci TIMESTAMP con un'ora di scadenza nel formato RFC 3339. Ad esempio, 2025-05-01T17:05:00Z. L'ora di scadenza determina quando la funzionalità dell'utilità di diagnostica viene disattivata automaticamente. Poiché l'utilità di diagnostica è disponibile per chiunque abbia accesso al cluster, l'impostazione dell'ora di scadenza in modo appropriato contribuisce a garantire che l'utilità non rimanga attiva più a lungo del necessario. Quando imposti l'ora di scadenza, ti consigliamo di impostarla a 12 ore in futuro, anche se qualsiasi ora in futuro è valida.

  3. Salva le modifiche ed esci dall'editor di testo per applicare il manifest al cluster.

Utilizzare l'utilità di diagnostica per simulare un accesso

Una volta attivata l'utilità di diagnostica, puoi simulare un evento di accesso e ottenere le informazioni di diagnostica corrispondenti che puoi utilizzare per risolvere i problemi con un provider specifico.

  1. Apri la pagina di diagnostica in un browser accedendo al seguente URL:

    APISERVER-URL/diagnose

    Sostituisci APISERVER_URL con il nome di dominio completo (FQDN) del cluster. Ad esempio, https://apiserver.example.com.

    Se riscontri un errore di tipo "Accesso negato", come il seguente:

    forbidden: user \"system:anonymous\" cannot get path \"/diagnose\"

    Aggiungi il valore del numero di porta :11001 a APISERVER_URL. Ad esempio, https://apiserver.example.com:11001/diagnose.

    La pagina di diagnostica mostra un elenco di provider OIDC configurati per il cluster.

  2. Seleziona il provider per cui vuoi risolvere i problemi.

  3. Accedi come di consueto.

    Al termine della procedura di accesso, l'utilità mostra una pagina con informazioni di diagnostica che possono aiutarti a risolvere i problemi.

Utilizzare la pagina di diagnostica per risolvere i problemi di accesso

La pagina di diagnostica fornisce un riepilogo dell'autenticazione, suddiviso in tre sezioni:

  • Stato: contiene Success o Failed, a seconda che l' autenticazione sia riuscita o meno.

  • Provider di identità: contiene dettagli, come Name, Client ID e UserClaim, sul provider utilizzato per l'accesso.

  • Token ID: contiene informazioni sul token ID recuperato da il cluster utilizzando il provider specificato. Il token ID è un oggetto JSON contenente un insieme di coppie chiave-valore. Le chiavi potrebbero includere iss, aud, sub ed email.

Risolvere i problemi relativi all'autenticazione riuscita

Se il contenuto della sezione Stato indica che l'autenticazione è riuscita e riscontri ancora problemi, la causa potrebbe essere la mancanza di controlli dell'accesso basati sui ruoli (RBAC). Per ulteriori informazioni sulla risoluzione dei problemi, consulta La sezione RBAC per i gruppi non funziona per i provider OIDC providers per ulteriori informazioni sulla risoluzione dei problemi.

Risolvere i problemi relativi all'autenticazione non riuscita

Se il contenuto della sezione Stato indica che l'autenticazione non è riuscita, inizia cercando le incoerenze tra le sezioni Provider di identità e Token ID.

Ecco alcuni requisiti di autenticazione da controllare:

  • Se il campo UserClaim in Provider di identità è vuoto, la sezione Token ID deve contenere un campo denominato sub. Un campo sub mancante indica che si è verificato un problema con il token ID.

  • Il valore del campo UserClaim in Provider di identità deve essere una chiave nella sezione Token ID. Ad esempio, se il campo UserClaim è impostato su email, deve essere presente un campo denominato email in Token ID.

  • Il valore del campo GroupsClaim in Provider di identità deve essere una chiave in Token ID. Ad esempio, se il campo GroupsClaim è impostato su groupsList (per un provider che supporta i gruppi), deve essere presente un campo denominato groupsList in Token ID.

  • Il valore del campo Client ID in Provider di identità deve essere contenuto nel valore del campo aud nella sezione Token ID.

Se una delle condizioni precedenti non è soddisfatta, consulta una delle seguenti guide per ulteriori dettagli su come configurare correttamente i cluster per l'autenticazione:

Utilizzare i log per ulteriori risoluzioni dei problemi

I log dei pod del servizio di identità contengono ulteriori informazioni di debug. Per utilizzare questi log:

  1. Attiva il log di debug.
  2. Controlla il log dei container.