Soluciona problemas de autenticación de terceros con una utilidad de diagnóstico

Puedes usar una utilidad de diagnóstico para solucionar problemas de autenticación basados en FQDN en clústeres miembros de la flota. Si tienes dificultades para autenticarte en un clúster con un proveedor de OIDC específico, puedes habilitar la herramienta y usarla para identificar rápidamente los problemas de configuración simulando flujos de acceso con tu proveedor de OIDC. Este documento solo se aplica a los tipos de clústeres compatibles.

La utilidad de diagnóstico solo está disponible en clústeres individuales que ejecutan la versión 1.32 o posterior y solo admite OIDC.

Habilita la utilidad de diagnóstico

La utilidad de diagnóstico está inhabilitada de forma predeterminada y se debe habilitar antes de que puedas usarla para solucionar problemas. Para habilitarla, sigue estas instrucciones:

  1. Abre el recurso personalizado ClientConfig para editarlo:

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

    El manifiesto debería ser similar al siguiente:

    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. Como se muestra en el siguiente ejemplo, agrega una sección identityServiceOptions al manifiesto de ClientConfig para especificar la configuración de la utilidad de diagnóstico:

    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
    

    Reemplaza TIMESTAMP por una hora de vencimiento en formato RFC 3339. Por ejemplo, 2025-05-01T17:05:00Z. La hora de vencimiento determina cuándo se desactiva automáticamente la función de utilidad de diagnóstico. Debido a que la utilidad de diagnóstico está disponible para cualquier persona con acceso al clúster, configurar la hora de vencimiento de forma adecuada ayuda a garantizar que la utilidad no permanezca habilitada más tiempo del necesario. Cuando configures la hora de vencimiento, se recomienda establecerla en 12 horas en el futuro, aunque cualquier hora en el futuro es válida.

  3. Guarda los cambios y cierra el editor de texto para aplicar el manifiesto al clúster.

Usa la utilidad de diagnóstico para simular un acceso

Una vez que se habilita la utilidad de diagnóstico, puedes simular un evento de acceso y obtener la información de diagnóstico correspondiente que puedes usar para solucionar problemas con un proveedor específico.

  1. Para abrir la página de diagnóstico en un navegador, navega a la siguiente URL:

    APISERVER-URL/diagnose
    

    Reemplaza APISERVER_URL por el nombre de dominio completamente calificado (FQDN) de tu clúster. Por ejemplo, https://apiserver.example.com.

    Si encuentras un error prohibido, como el siguiente:

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

    Agrega el valor del número de puerto :11001 a APISERVER_URL. Por ejemplo, https://apiserver.example.com:11001/diagnose.

    En la página de diagnóstico, se muestra una lista de los proveedores de OIDC configurados para tu clúster.

  2. Selecciona el proveedor en el que deseas solucionar problemas.

  3. Accede como de costumbre.

    Al final del proceso de acceso, la utilidad muestra una página con información de diagnóstico que puede ayudarte a solucionar problemas.

Usa la página de diagnóstico para solucionar problemas de acceso

La página de diagnóstico proporciona un resumen de autenticación, que se divide en tres secciones:

  • Estado: Contiene Success o Failed, según si la autenticación se realizó correctamente o no.

  • Proveedor de identidad: Contiene detalles, como Name, Client ID y UserClaim, sobre el proveedor que se usó para acceder.

  • Token de ID: Contiene información sobre el token de ID que recuperó el clúster con el proveedor determinado. El token de ID es un objeto JSON que contiene un conjunto de pares clave-valor. Las claves pueden incluir iss, aud, sub y email.

Soluciona problemas de autenticación exitosa

Si el contenido de la sección Estado indica que la autenticación se realizó correctamente y sigues teniendo problemas, es posible que la causa sea la falta de controles de acceso basados en roles (RBAC). Para obtener información adicional sobre la solución de problemas, consulta RBAC para grupos que no funcionan para proveedores de OIDC.

Soluciona problemas de falla de autenticación

Si el contenido de la sección Estado indica que falló la autenticación, comienza por buscar incoherencias entre las secciones Proveedor de identidad y Token de ID.

Estos son algunos requisitos de autenticación que debes verificar:

  • Si el campo UserClaim en Proveedor de identidad está vacío, la sección Token de ID debe contener un campo llamado sub. Un campo sub faltante es una indicación de que hay un problema con el token de ID.

  • El valor del campo UserClaim en Proveedor de identidad debe ser una clave en la sección Token de ID. Por ejemplo, si el campo UserClaim está configurado como email, debe haber un campo llamado email en Token de ID.

  • El valor del campo GroupsClaim en Proveedor de identidad debe ser una clave en Token de ID. Por ejemplo, si el campo GroupsClaim está configurado como groupsList (para un proveedor que admite grupos), debe haber un campo llamado groupsList en Token de ID.

  • El valor del campo Client ID en Proveedor de identidad debe estar dentro del valor del campo aud en la sección Token de ID.

Si no se cumple alguna de las condiciones anteriores, consulta una de las siguientes guías para obtener más detalles sobre cómo configurar correctamente tus clústeres para la autenticación:

Usa registros para solucionar problemas adicionales

Los registros de Pod del servicio de identidad contienen información de depuración adicional. Para usar estos registros, haz lo siguiente:

  1. Habilita el registro de depuración.
  2. Verifica el registro del contenedor.