Configurer les clusters membres du parc pour l'authentification OIDC

Ce document explique comment les administrateurs de cluster ou les opérateurs d'application peuvent configurer des clusters pour qu'ils soient compatibles avec l'authentification à l'aide d'un fournisseur OpenID Connect (OIDC) tiers.

Limites

Vous devez utiliser un type de cluster compatible avec OIDC.

Avant de commencer

  1. Install the Google Cloud CLI.

  2. Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

  3. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  4. Après avoir initialisé la gcloud CLI, mettez-la à jour et installez les composants requis : 

    gcloud components update
gcloud components install kubectl
  5. Assurez-vous que l'administrateur de votre plate-forme vous a fourni toutes les informations nécessaires sur le fournisseur. Pour en savoir plus, consultez Partager les informations du fournisseur d'identité.
  6. Pour vous authentifier à l'aide de la console Google Cloud , enregistrez chaque cluster que vous souhaitez configurer dans le parc de votre projet. Pour en savoir plus, consultez Présentation de la création de flottes.
  7. Pour vous connecter au plan de contrôle d'un cluster AWS ou Azure situé en dehors de votre réseau VPC actuel via un hôte bastion, assurez-vous d'avoir créé l'hôte bastion et d'avoir démarré un tunnel SSH sur le port 8118. Lorsque vous exécutez des commandes kubectl dans ce document, ajoutez HTTPS_PROXY=http://localhost:PORT devant les commandes, où PORT correspond au numéro de port que vous avez utilisé lorsque vous avez démarré le tunnel SSH.
  8. Pour les clusters GKE sur Google Cloud, enregistrez les clusters dans votre parc.

Configurer les clusters

Pour configurer l'authentification à un cluster à l'aide d'OIDC, ajoutez les informations suivantes à une ressource personnalisée Kubernetes nommée ClientConfig :

  • Informations sur votre fournisseur d'identité, comme un ID client et un code secret.
  • Informations sur les jetons Web JSON (JWT) utilisés par votre fournisseur d'identité pour l'authentification.
  • Tous les champs d'application ou paramètres supplémentaires propres à votre fournisseur d'identité.

Pour en savoir plus sur les informations dont vous avez besoin de la part de l'administrateur de votre plate-forme ou de la personne qui gère l'identité dans votre organisation, consultez Partager les informations du fournisseur d'identité.

Le cluster utilise les champs de la ressource personnalisée ClientConfig pour interagir avec votre fournisseur d'identité. Chaque cluster dispose d'une ressource ClientConfig nommée default dans l'espace de noms kube-public. Les champs spécifiques que vous modifiez dépendent de votre fournisseur d'identité.

Pour modifier le ClientConfig default, assurez-vous de pouvoir vous connecter à votre cluster kubectl, puis exécutez la commande suivante :

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

Remplacez KUBECONFIG_PATH par le chemin d'accès au fichier kubeconfig de votre cluster, par exemple $HOME/.kube/config.

Un éditeur de texte charge la ressource ClientConfig de votre cluster. Ajoutez l'objet spec.authentication.oidc comme indiqué dans l'exemple suivant. Ne modifiez aucune donnée par défaut déjà écrite.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_AUTHORITY_DATA
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL
# Rest of the resource is managed by Google. DO NOT MODIFY.

Par exemple, examinez les champs de jeton d'identité suivants :

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  # Multiple lines are omitted here
}

Dans cet exemple, iss correspond à l'URI du fournisseur d'identité, sub identifie l'utilisateur et groupList répertorie les groupes de sécurité auxquels l'utilisateur appartient. Cet exemple ne montre qu'un échantillon des champs que le jeton réel peut contenir.

Pour l'exemple de jeton précédent, vous devez mettre à jour les champs suivants dans l'objet spec.authentication.oidc de ClientConfig :

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
# Multiple lines are omitted here

Vous pouvez ajouter plusieurs configurations de fournisseurs d'identité OIDC, LDAP et SAML au même fichier ClientConfig. Le cluster tente de s'authentifier avec chaque configuration dans l'ordre dans lequel elles sont définies, et s'arrête après la première authentification réussie. L'exemple ClientConfig suivant définit plusieurs fournisseurs d'identité dans un ordre spécifique :

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - aws:
      region: us-west-2
    name: AWS Login
  - ldap:
  # Multiple lines are omitted here.
  - saml:
  # Multiple lines are omitted here.
  - azureAD:
  # Multiple lines are omitted here.
  - oidc:
    name: Okta OIDC
  # Multiple lines are omitted here.
  - oidc:
    name: Google OIDC
  # Multiple lines are omitted here.

Champs OIDC ClientConfig

Le tableau suivant décrit les champs de l'objet oidc ClientConfig. Les champs que vous devez ajouter dépendent des jetons de votre fournisseur d'identité et de la façon dont l'administrateur de votre plate-forme a configuré le fournisseur.

Champ Obligatoire Description Format
nom oui Nom que vous souhaitez utiliser pour identifier cette configuration, généralement le nom du fournisseur d'identité. Le nom d'une configuration doit commencer par une lettre suivie de 1 à 39 lettres minuscules, chiffres ou traits d'union, et ne peut pas se terminer par un trait d'union. Chaîne
certificateAuthorityData Non Si fournie par votre administrateur de plate-forme, une chaîne de certificat encodée au format PEM pour le fournisseur d'identité. Incluez la chaîne obtenue dans certificateAuthorityData en tant que ligne unique. Chaîne
clientID Oui ID client du fournisseur d'identité. Chaîne
clientSecret Non Secret partagé entre l'application cliente OIDC et le fournisseur OIDC. Chaîne
deployCloudConsoleProxy Non Indique si un proxy est déployé et permet à la console Google Cloud de se connecter à un fournisseur d'identité sur site qui n'est pas accessible publiquement sur Internet. Par défaut, cette valeur est définie sur false. Booléen
extraParams Non Paramètres de clé=valeur supplémentaires à envoyer au fournisseur d'identité, spécifiés sous forme de liste séparée par des virgules (par exemple, "prompt=consent,access_type=offline"). Liste d'éléments séparés par une virgule
groupsClaim Non La revendication JWT (nom du champ) que votre fournisseur utilise pour renvoyer les groupes de sécurité d'un compte. Chaîne
groupPrefix Non Le préfixe que vous souhaitez ajouter aux noms de groupe de sécurité pour éviter les conflits avec les noms existants dans vos règles de contrôle d'accès si vous avez des configurations pour plusieurs fournisseurs d'identité (généralement le nom du fournisseur). Chaîne
issuerURI Oui L'URI vers lequel les requêtes d'autorisation sont envoyées à votre fournisseur d'identité. L'URI doit utiliser le protocole HTTPS et ne doit pas se terminer par une barre oblique. Chaîne d'URL
kubectlRedirectURI Oui Port et URL de redirection utilisés par gcloud CLI et spécifiés par l'administrateur de la plate-forme à l'enregistrement, généralement au format http://localhost:PORT/callback. Chaîne d'URL
scopes Oui Niveaux d'accès supplémentaires à envoyer au fournisseur OpenID. Par exemple, Microsoft Azure et Okta nécessitent le niveau d'accès offline_access. Liste d'éléments séparés par une virgule
userClaim Non La revendication JWT (nom du champ) utilisée par votre fournisseur pour identifier un compte utilisateur. Si vous ne spécifiez pas de valeur ici, la valeur par défaut est "sub ", qui est la revendication d'ID utilisateur utilisée par de nombreux fournisseurs. Vous pouvez choisir d'autres revendications, telles que l'adresse e-mail our le nom, selon le fournisseur OpenID. Les revendications autres que l'adresse e-mail sont précédées de l'URL de l'émetteur pour éviter les conflits de noms. Chaîne
userPrefix Non Le préfixe que vous souhaitez ajouter aux revendications de l'utilisateur pour éviter les conflits avec les noms existants, si vous ne souhaitez pas utiliser le préfixe par défaut. Chaîne
enableAccessToken Non Si cette option est activée, le cluster peut utiliser le point de terminaison userinfo du fournisseur d'identité pour obtenir des informations sur les groupes lorsqu'un utilisateur se connecte à partir de la ligne de commande. Cela vous permet d'utiliser des groupes de sécurité pour l'autorisation si vous avez un fournisseur (comme Okta) qui fournit des revendications de groupe à partir de ce point de terminaison. Si ce champ n'est pas défini, la valeur correspond à false. Booléen
proxy Non Adresse du serveur proxy à utiliser pour se connecter au fournisseur d'identité, le cas échéant. Vous devrez peut-être définir cette option si, par exemple, votre cluster se trouve sur un réseau privé et doit se connecter à un fournisseur d'identité public. Exemple : http://user:password@10.10.10.10:8888. Chaîne

Après avoir modifié votre ClientConfig, enregistrez le fichier pour mettre à jour la ClientConfig de votre cluster. Si vous commettez des erreurs de syntaxe, vous êtes invité à les corriger et à enregistrer le fichier.

Configurations spécifiques aux fournisseurs

Cette section fournit des conseils de configuration pour certains des fournisseurs OIDC les plus couramment utilisés, y compris des exemples de configurations que vous pouvez copier et modifier avec vos propres détails.

Microsoft Entra ID

Il s'agit de la configuration par défaut pour configurer un cluster pour l'authentification avec Microsoft Entra ID. Cette configuration permet au cluster d'obtenir des informations sur les utilisateurs et les appartenances aux groupes à partir de Microsoft Entra ID, et vous permet de configurer le contrôle des accès basé sur les rôles Kubernetes (RBAC) en fonction des groupes. Toutefois, l'utilisation de cette configuration vous limite à la récupération d'environ 200 groupes par utilisateur.

Si vous devez récupérer plus de 200 groupes par utilisateur, consultez les instructions pour Microsoft Entra ID (Configuration avancée).

# Multiple lines are omitted here.
spec:
  authentication:
  - name: oidc-entraid
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

Remplacez les éléments suivants :

  • CLIENT_ID : ID client de Microsoft Entra ID.
  • CLIENT_SECRET : le secret partagé entre l'application cliente OIDC et le fournisseur OIDC.
  • TENANT_ID : le type de compte Microsoft Entra ID à authentifier. Les valeurs acceptées sont l'ID de locataire ou le nom du locataire pour les comptes appartenant à un locataire spécifique. Le nom du locataire est également appelé domaine principal. Pour savoir comment trouver ces valeurs, consultez Rechercher l'ID de locataire Microsoft Entra et le nom de domaine principal.
  • PORT : le numéro de port choisi pour l'URL de redirection utilisée par gcloud CLI, spécifié par l'administrateur de votre plate-forme lors de l'enregistrement.

Microsoft Entra ID (avancé)

Cette configuration facultative pour Microsoft Entra ID permet au cluster de récupérer des informations sur les utilisateurs et les groupes sans limitation du nombre de groupes par utilisateur, à l'aide de l'API Microsoft Graph.

Pour en savoir plus sur les plates-formes compatibles avec cette configuration, consultez la section Configuration avancée pour Microsoft Entra ID.

Si vous devez récupérer moins de 200 groupes par utilisateur, nous vous recommandons d'utiliser la configuration par défaut à l'aide d'une ancre oidc dans votre ClientConfig. Pour en savoir plus, consultez les instructions pour Microsoft Entra ID.

Tous les champs de l'exemple de configuration suivant sont requis.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM
# Multiple lines are omitted here. Do not modify any pre-filled data.

Remplacez les éléments suivants :

  • NAME : nom que vous souhaitez utiliser pour identifier cette configuration, généralement le nom du fournisseur d'identité. Le nom d'une configuration doit commencer par une lettre suivie de 1 à 39 lettres minuscules, chiffres ou traits d'union, et ne peut pas se terminer par un trait d'union.
  • PROXY_URL : adresse du serveur proxy à utiliser pour se connecter au fournisseur d'identité, le cas échéant. Vous devrez peut-être définir cette option si, par exemple, votre cluster se trouve sur un réseau privé et doit se connecter à un fournisseur d'identité public. Exemple : http://user:password@10.10.10.10:8888.
  • CLIENT_ID : ID client de Microsoft Entra ID.
  • CLIENT_SECRET : le secret partagé entre l'application cliente OIDC et le fournisseur OIDC.
  • TENANT : le type de compte Microsoft Entra à authentifier. Les valeurs acceptées sont l'ID de locataire ou le nom du locataire pour les comptes appartenant à un locataire spécifique. Le nom du locataire est également appelé domaine principal. Pour savoir comment trouver ces valeurs, consultez Rechercher l'ID de locataire Microsoft Entra et le nom de domaine principal.
  • PORT : le numéro de port choisi pour l'URL de redirection utilisée par gcloud CLI, spécifié par l'administrateur de votre plate-forme lors de l'enregistrement.
  • GROUP_FORMAT : format dans lequel vous souhaitez récupérer les informations de groupe. Ce champ peut prendre des valeurs correspondant aux valeurs ID ou NAME des groupes d'utilisateurs. Notez que ce paramètre n'est disponible que pour les clusters dans les déploiements Google Distributed Cloud sur Bare Metal.
  • USER_CLAIM (facultatif) : revendication de jeton JWT (nom de champ) que votre fournisseur utilise pour identifier un compte. Si vous ne spécifiez pas de valeur ici, le cluster utilise une valeur dans l'ordre "email", "preferred_username" ou "sub" pour récupérer les informations sur l'utilisateur. Cet attribut peut être utilisé à partir de la version 1.28.

Okta

Vous trouverez ci-dessous la procédure à suivre pour configurer l'authentification en utilisant à la fois les utilisateurs et les groupes avec Okta comme fournisseur d'identité. Cette configuration permet au cluster de récupérer les revendications des utilisateurs et des groupes à l'aide d'un jeton d'accès et du point de terminaison userinfo d'Okta.

# Multiple lines are omitted here.
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email
# Multiple lines are omitted here. Do not modify any pre-filled data.

Limites d'accès relatives aux groupes

Pour les utilisateurs d'Okta, le cluster peut récupérer des informations de groupes pour les utilisateurs dont les noms de groupe, s'ils sont concaténés, ne dépassent pas 170 000 caractères. Cela correspond à une adhésion d'environ 650 groupes en fonction de la longueur maximale de groupe d'Okta. Si l'utilisateur est membre d'un trop grand nombre de groupes, l'appel d'authentification échoue.

Étape suivante

Une fois la configuration appliquée, découvrez comment configurer l'accès des utilisateurs aux clusters.