Vous consultez la documentation d'une version précédente de GKE On-Prem. Consultez la documentation la plus récente.

S'authentifier avec OpenID Connect (OIDC)

Cette page explique comment configurer GKE On-Prem pour utiliser un fournisseur OpenID pour l'authentification auprès des clusters d'utilisateur. Pour savoir comment utiliser OIDC avec AD FS, consultez la page Assurer l'authentification avec OIDC et AD FS.

Pour une présentation du processus d'authentification de GKE On-Prem, consultez la page Authentification.

Aperçu

GKE On-Prem est compatible avec OpenID Connect (OIDC) en tant que mécanisme d'authentification pour interagir avec le serveur d'API Kubernetes d'un cluster d'utilisateur. OIDC vous permet de gérer l'accès aux clusters Kubernetes en utilisant les procédures standard de votre organisation pour créer, activer et désactiver des comptes d'employés.

Deux options s'offrent à vous pour utiliser le flux d'authentification OIDC :

  • Un employé peut utiliser kubectl pour lancer un flux OIDC. Pour que ce flux soit automatique, GKE On-Prem fournit le plug-in Kubectl pour OIDC, un plug-in kubectl.

  • Un employé peut utiliser Google Cloud Console pour lancer un flux d'authentification OIDC.

Dans cet exercice, vous allez configurer les deux options : kubectl et Cloud Console.

Avant de commencer

Dans cette rubrique, nous partons du principe que vous connaissez bien OAuth 2.0 et OpenID Connect. Dans cette rubrique, nous partons du principe que vous connaissez bien les champs d'application et les revendications OpenID.

Choisir un fournisseur OpenID

Cette section s'adresse aux administrateurs.

Vous pouvez utiliser n'importe quel fournisseur OpenID de votre choix. Pour obtenir la liste des fournisseurs certifiés, consultez la page Certification OpenID.

Une possibilité consiste à utiliser Active Directory Federated Services (ADFS) en tant que fournisseur OpenID, et utiliser une instance sur site d'Active Directory comme base de données des employés. Pour en savoir plus, consultez la section Assurer l'authentification avec OIDC et AD FS.

Télécharger le plug-in Kubectl pour OIDC

Cette section s'adresse aux administrateurs et aux employés qui souhaitent utiliser le plug-in Kubectl pour OIDC.

Téléchargez le plug-in et définissez les autorisations d'accès :

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

Installer le plug-in

Installez le plug-in en déplaçant le fichier exécutable à n'importe quel emplacement de votre PATH. Le fichier exécutable doit être nommé kubectl-oidc. Pour en savoir plus, consultez la section Installer des plug-ins Kubectl.

Créer une URL de redirection pour le plug-in Kubectl pour OIDC

Cette section s'adresse aux administrateurs.

Dans le cadre de l'établissement d'une relation avec votre fournisseur OpenID, vous devez spécifier une URL de redirection permettant au fournisseur de renvoyer des jetons d'ID au plug-in Kubectl pour OIDC. Le plug-in Kubectl pour OIDC s'exécute sur la machine locale de chaque employé et écoute sur le port de votre choix. Choisissez un numéro de port supérieur à 1 024 et adapté à cet usage. L'URL de redirection est alors la suivante :

http://localhost:[PORT]/callback

[PORT] est votre numéro de port.

Lorsque vous configurez votre fournisseur OpenID, spécifiez http://localhost:[PORT]/callback comme l'une de vos URL de redirection. La procédure à suivre pour cela dépend de votre fournisseur.

Configurer une URL de redirection pour Cloud Console

Cette section s'adresse aux administrateurs.

En plus de disposer d'une URL de redirection pour kubectl, vous avez besoin d'une URL de redirection pour Cloud Console. L'URL de redirection de Cloud Console est la suivante :

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

Lorsque vous configurez votre fournisseur OIDC, spécifiez https://console.cloud.google.com/kubernetes/oidc comme URL de redirection. La procédure à suivre pour cela dépend de votre fournisseur.

Enregistrer des applications clientes auprès du fournisseur OpenID

Cette section s'adresse aux administrateurs.

Pour que vos employés puissent utiliser le plug-in Kubectl pour OIDC ou Cloud Console avec votre fournisseur OpenID, vous devez enregistrer ces deux clients auprès du fournisseur OpenID. L'enregistrement comprend les étapes suivantes :

  • Découvrir l'URI d'émetteur du fournisseur. C'est là que le plug-in Kubectl pour OIDC ou Cloud Console envoie les demandes d'authentification.

  • Indiquer au fournisseur l'URL de redirection du plug-in Kubectl pour OIDC.

  • Indiquer au fournisseur l'URL de redirection pour Cloud Console. Il s'agit de https://console.cloud.google.com/kubernetes/oidc.

  • Établir un ID client unique. Il s'agit de l'ID utilisé par le fournisseur pour identifier le plug-in Kubectl pour OIDC et Cloud Console.

  • Établir un code secret de client unique. Le plug-in Kubectl pour OIDC et Cloud Console utilisent tous deux ce code secret pour s'authentifier auprès du fournisseur OpenID.

  • Établir un champ d'application personnalisé que le plug-in Kubectl pour OIDC ou Cloud Console peut utiliser pour demander les groupes de sécurité de l'utilisateur.

  • Établir un nom de revendication personnalisé que le fournisseur utilisera pour renvoyer les groupes de sécurité de l'utilisateur.

La procédure à suivre dépend de votre fournisseur OpenID. Pour savoir comment effectuer les étapes d'enregistrement avec AD FS, consultez la section Assurer l'authentification avec OIDC et AD FS.

Remplir la spécification oidc dans le fichier de configuration GKE On-Prem

Cette section s'adresse aux employés qui souhaitent créer un cluster configuré pour utiliser OIDC.

Avant de créer un cluster d'utilisateur, générez un fichier de configuration GKE On-Prem avec gkectl create-config. La configuration inclut la spécification oidc suivante. Renseignez oidc avec des valeurs spécifiques à votre fournisseur :

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl : Obligatoire. URL de votre fournisseur OpenID, telle que https://example.com/adfs. Les applications clientes, telles que le plug-in Kubectl pour OIDC et Cloud Console, envoient des demandes d'autorisation à cette URL. Le serveur de l'API Kubernetes utilise cette URL pour découvrir les clés publiques permettant de valider les jetons. Vous devez utiliser HTTPS.
  • clientid : Obligatoire. ID de l'application cliente qui envoie des requêtes d'authentification au fournisseur OpenID. Le plug-in Kubectl pour OIDC et Cloud Console utilisent tous deux cet ID.
  • clientsecret : facultatif. Clé secrète de l'application cliente. Le plug-in Kubectl pour OIDC et Cloud Console utilisent tous deux cette clé.
  • username : facultatif. Revendication JWT à utiliser comme nom d'utilisateur. La valeur par défaut est sub, qui est censé être un identifiant unique de l'utilisateur final. Vous pouvez choisir d'autres revendications, telles que email ou name, en fonction du fournisseur OpenID. Toutefois, les revendications autres que email sont précédées de l'URL de l'émetteur afin d'éviter les conflits avec les noms d'autres plug-ins.
  • usernameprefix : facultatif. Préfixe précédé des revendications de nom d'utilisateur pour éviter les conflits avec les noms existants. Si vous ne fournissez pas ce champ et que username est une valeur autre que email, le préfixe est défini par défaut sur issuerurl#. Vous pouvez utiliser la valeur - pour désactiver tous les préfixes.
  • group : facultatif. Revendication JWT que le fournisseur utilisera pour renvoyer vos groupes de sécurité.
  • groupprefix : facultatif. Préfixe ajouté aux revendications de groupe pour éviter les conflits avec les noms existants. Par exemple, avec un groupe foobar et un préfixe gid-, gid-foobar.
  • scopes : facultatif. Champs d'application supplémentaires à envoyer au fournisseur OpenID sous forme de liste délimitée par des virgules.
  • extraparams : facultatif. Paramètres de clé-valeur supplémentaires à envoyer au fournisseur OpenID sous forme de liste délimitée par des virgules.
  • usehttpproxy : facultatif. Spécifie si un proxy inverse doit être déployé dans le cluster pour permettre à Connect Agent d'accéder au fournisseur OIDC sur site pour authentifier les utilisateurs. La valeur doit être une chaîne : "true" ou "false".
  • capath : facultatif. Chemin d'accès au certificat de l'autorité de certification qui a émis le certificat Web de votre fournisseur d'identité. Cette valeur peut ne pas être nécessaire. Par exemple, si le certificat de votre fournisseur d'identité a été émis par une autorité de certification publique connue, vous n'avez pas besoin de fournir une valeur ici.

Exemple : autoriser des utilisateurs et des groupes

De nombreux fournisseurs codent les propriétés d'identification des utilisateurs, telles que les e-mails et les ID utilisateur, dans un jeton. Cependant, ces propriétés présentent des risques implicites pour les règles d'authentification :

  • Les ID utilisateur peuvent compliquer la lecture et l'audit des stratégies.
  • Les e-mails peuvent créer un risque de disponibilité (si un utilisateur modifie son adresse e-mail principale) et éventuellement un risque de sécurité (si un e-mail peut être réattribué).

Par conséquent, il est recommandé d'utiliser des stratégies de groupe, car un ID de groupe peut être à la fois persistant et plus facile à auditer.

Supposons que votre fournisseur crée des jetons d'identité qui incluent les champs suivants :

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList: ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}
Avec ce format de jeton, vous devez remplir la spécification oidc de votre fichier de configuration comme suit :
issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

Une fois le cluster utilisateur créé, vous pouvez utiliser le contrôle des accès basé sur les rôles Kubernetes (RBAC) pour accorder un accès privilégié aux utilisateurs authentifiés. Par exemple, vous pouvez créer un objet ClusterRole qui accorde à ses utilisateurs un accès en lecture seule aux codes secrets du cluster, et créer une ressource ClusterRoleBinding pour lier le rôle au groupe authentifié :

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

Enregistrer le certificat de l'autorité de certification du serveur d'API Kubernetes

Cette section s'adresse aux employés qui ont créé un cluster d'utilisateur et souhaitent à présent utiliser le plug-in Kubectl pour OIDC.

Votre cluster d'utilisateur dispose d'un serveur d'API Kubernetes. De plus, le fichier kubeconfig de votre cluster d'utilisateur stocke le certificat de l'autorité de certification ayant émis un certificat sur le serveur d'API Kubernetes. Le certificat de l'autorité de certification est la valeur encodée en base64 du champ certificate-authority-data. Vous devez décoder cette valeur et la stocker dans un fichier local, tel que server-ca-cert :

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

Générer le fichier de configuration d'authentification du client

Cette section s'adresse aux employés qui ont créé un cluster d'utilisateur et souhaitent à présent utiliser le plug-in Kubectl pour OIDC.

Pour générer un fichier de configuration d'authentification du client, saisissez la commande suivante :

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

où :

  • [ISSUER_URI] est votre URI d'émetteur.
  • [REDIRECT_URL] est l'URL de redirection du plug-in Kubectl pour OIDC.
  • [CLIENT_ID] est l'ID client du plug-in Kubectl pour OIDC.
  • [CLIENT_SECRET] est le code secret du client pour le plug-in Kubectl pour OIDC.
  • [USER_CLUSTER_NAME] est le nom de votre cluster d'utilisateur.
  • [CLUSTER_URL] est l'URL du serveur d'API Kubernetes du cluster d'utilisateur.
  • [SERVER_CA_FILE] est le chemin d'accès au certificat de l'autorité de certification ayant émis un certificat sur le serveur d'API Kubernetes. Il s'agit du fichier de certificat que vous avez créé dans la section précédente.
  • [PROVIDER_CA_CERT] est le chemin d'accès au certificat de l'autorité de certification ayant signé le certificat du fournisseur OpenID. Il s'agit de la valeur de oidc:cacert dans votre fichier de configuration de cluster.
  • [CUSTOM_SCOPES] est la liste de vos champs d'application personnalisés séparés par des virgules pour les groupes de sécurité. Il s'agit de la valeur de oidc:scopes dans votre fichier de configuration de cluster.
  • --extra-params [KEY]=[VALUE], ... est une liste de paires clé-valeur séparées par des virgules à inclure dans les demandes d'autorisation adressées au fournisseur 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

où :

  • [ISSUER_URI] est votre URI d'émetteur.
  • [REDIRECT_URL] est l'URL de redirection du plug-in Kubectl pour OIDC.
  • [CLIENT_ID] est l'ID client du plug-in Kubectl pour OIDC.
  • [CLIENT_SECRET] est le code secret du client pour le plug-in Kubectl pour OIDC.
  • [USER_CLUSTER_NAME] est le nom de votre cluster d'utilisateur.
  • [CLUSTER_URL] est l'URL du serveur d'API Kubernetes du cluster d'utilisateur.
  • [SERVER_CA_FILE] est le chemin d'accès au certificat de l'autorité de certification ayant émis un certificat sur le serveur d'API Kubernetes. Il s'agit du fichier de certificat que vous avez créé dans la section précédente.
  • [PROVIDER_CA_CERT] est le chemin d'accès au certificat de l'autorité de certification ayant signé le certificat du fournisseur OpenID. Il s'agit de la valeur de oidc:cacert dans votre fichier de configuration de cluster.
  • [CUSTOM_SCOPES] est la liste de vos champs d'application personnalisés séparés par des virgules pour les groupes de sécurité. Il s'agit de la valeur de oidc:scopes dans votre fichier de configuration de cluster.
  • --extra-params [KEY]=[VALUE], ... est une liste de paires clé-valeur séparées par des virgules à inclure dans les demandes d'autorisation adressées au fournisseur OpenID.

Cette commande génère un fichier de configuration d'authentification client appelé client-config.yaml. Ne modifiez pas manuellement ce fichier.

Authentifier contre un cluster utilisateur à l'aide du plug-in Kubectl pour OIDC

Cette section s'adresse aux employés qui ont créé un cluster d'utilisateur et souhaitent à présent utiliser le plug-in Kubectl pour OIDC.

  1. Initialisez le plug-in à l'aide du fichier client-config.yaml :

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

    où :

    • [NAME] est votre nom d'utilisateur.
    • [KUBECONFIG_OUTPUT_PATH] est le chemin d'accès au fichier kubeconfig où le plug-in Kubectl pour OIDC stockera les identifiants.

    kubectl oidc login lance un navigateur dans lequel vous pouvez saisir vos identifiants.

    Le fichier kubeconfig fourni contient désormais un jeton d'ID que kubectl peut utiliser pour s'authentifier auprès du serveur d'API Kubernetes sur le cluster d'utilisateur.

    Remarque : les utilisateurs de Windows devront peut-être exécuter la commande en tant que connexion kubectl-oidc.exe au lieu de kubectl oidc login.

  2. Vérifiez que l'authentification a réussi en exécutant une commande kubectl. Exemple :

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Utiliser OIDC avec Google Cloud Console

Cette section s'adresse aux employés qui ont créé un cluster d'utilisateur et souhaitent à présent utiliser Google Cloud Console pour s'authentifier auprès du cluster.

  1. Vérifiez que votre cluster est  configuré pour OIDC.

  2. Vérifiez que votre cluster a été enregistré avec Google Cloud, soit automatiquement lors de sa création, soit manuellement.

  3. Accédez à la page Clusters Kubernetes dans Cloud Console.

    Accéder à la page des clusters Kubernetes

  4. Dans la liste des clusters, localisez votre cluster GKE On-Prem, puis cliquez sur Connexion.

  5. Sélectionnez Authentifier avec le fournisseur d'identité configuré pour le cluster, puis cliquez sur CONNEXION.

    Vous serez redirigé vers votre fournisseur d'identité, où vous devrez peut-être vous connecter ou autoriser Cloud Console à accéder à votre compte. Vous serez ensuite redirigé vers la page Clusters Kubernetes dans Cloud Console.

Résoudre les problèmes liés à OIDC dans GKE On-Prem

Configuration non valide

Si Cloud Console ne peut pas lire la configuration OIDC de votre cluster, le bouton CONNEXION est désactivé.

Configuration du fournisseur non valide

Si la configuration de votre fournisseur d'identité est incorrecte, un message d'erreur s'affichera en provenance de votre fournisseur d'identité lorsque vous aurez cliqué sur CONNEXION. Suivez les instructions spécifiques au fournisseur pour configurer correctement le fournisseur ou votre cluster.

Autorisations non valides

Si vous avez terminé le flux d'authentification, mais que vous ne voyez toujours pas les détails du cluster, assurez-vous d'avoir accordé les autorisations RBAC appropriées au compte que vous avez utilisé avec OIDC. Notez qu'il peut s'agir d'un compte différent de celui que vous utilisez pour accéder à Cloud Console.

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

Vous pouvez rencontrer cette erreur si le serveur d'autorisation vous demande votre autorisation, mais que le paramètre d'authentification requis n'a pas été fourni. Fournissez le paramètre prompt=consent au champ oidc: extraparams du fichier de configuration GKE On-Prem et générez à nouveau le fichier d'authentification du client avec l'indicateur --extra-params prompt=consent.