Assurer l'authentification avec OIDC et AD FS

Cette page explique comment utiliser OIDC (OpenID Connect) avec AD FS (Active Directory Federation Services) pour configurer l'authentification pour les clusters d'utilisateurs GKE On-Prem.

Pour une présentation du flux d'authentification, consultez la page Authentification. Pour plus d'informations sur l'utilisation de fournisseurs OpenID autres qu'AD FS, consultez la section Authentification avec OpenID Connect.

Présentation

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.

Un employé peut utiliser le processus d'authentification OIDC de deux façons :

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

  • Il peut utiliser Google Cloud Console pour lancer un processus d'authentification OIDC.

Dans cet exercice, vous allez configurer les deux options : kubectl et la console Google Cloud. Vous utilisez un ensemble d'assistants de gestion AD FS pour configurer votre serveur AD FS et votre base de données d'employés AD.

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.

Cet article concerne les entreprises disposant de l'infrastructure suivante :

  • L'entreprise utilise Active Directory (AD) pour sa base de données d'employés.
  • L'entreprise exécute un serveur Active Directory Federation Services (AD FS).
  • Le serveur AD FS agit en tant que fournisseur OpenID.

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 serveur AD FS, vous devez spécifier une URL de redirection que le serveur AD FS peut utiliser pour 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

où [PORT] est votre numéro de port.

Lorsque vous configurez votre serveur AD FS, spécifiez http://localhost:[PORT]/callback comme l'une de vos URL de redirection.

Configurer une URL de redirection pour la console Google Cloud

Cette section s'adresse aux administrateurs.

En plus de disposer d'une URL de redirection pour le plug-in Kubectl pour OIDC, vous avez besoin d'une URL de redirection pour la console Google Cloud. L'URL de redirection de la console Google Cloud est la suivante :

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

Lorsque vous configurez votre serveur AD FS, indiquez https://console.cloud.google.com/kubernetes/oidc comme URL de redirection.

Configurer AD FS

Les sections suivantes expliquent comment configurer AD FS pour GKE On-Prem.

Définir des URL de redirection

  1. Ouvrez le volet de gestion AD FS.

  2. Sélectionnez Groupes d'applications > Actions > Ajouter un groupe d'applications.

  3. Sélectionnez Application de serveur. Saisissez le nom et la description de votre choix. Cliquez sur Suivant.

  4. Saisissez vos deux URL de redirection. Un ID client vous est attribué. Voici comment le serveur AD FS identifie le plug-in Kubectl pour OIDC et la console Google Cloud. Notez l'identifiant client pour pouvoir l'utiliser ultérieurement.

  5. Sélectionnez Générer une clé secrète partagée. Le plug-in Kubectl pour OIDC et la console Google Cloud utilisent ce secret pour s'authentifier auprès du serveur AD FS. Enregistrez le secret pour plus tard.

Configurer des groupes de sécurité (facultatif)

  1. Dans la gestion AD FS, sélectionnez Approbations par un tiers de confiance > Ajouter une approbation par un tiers de confiance.

  2. Sélectionnez Prise en charge des revendications, puis cliquez sur Démarrer.

  3. Sélectionnez Saisir manuellement les données concernant le tiers de confiance.

  4. Saisissez un nom à afficher.

  5. Ignorez les deux étapes suivantes.

  6. Saisissez un identifiant d'approbation par un tiers de confiance. Suggestion : token-groups-claim.

  7. Pour Stratégie de contrôle d'accès, sélectionnez Autoriser tout le monde. Cela signifie que tous les employés partagent leurs informations de groupe de sécurité avec le plug-in Kubectl pour OIDC et la console Google Cloud.

  8. Cliquez sur Terminer.

Mapper des attributs LDAP à des noms de revendication

  1. Dans la gestion AD FS, sélectionnez Approbations par des tiers de confiance > Éditer la stratégie d'émission de revendication.

  2. Sélectionnez Envoyer les attributs LDAP en tant que revendications, puis cliquez sur Suivant.

  3. Dans Nom de la règle de revendication, saisissez groups.

  4. Dans Liste des attributs, sélectionnez Active Directory.

  5. Dans la table, pour Attribut LDAP, sélectionnez :

    • AD FS version 5.0 ou ultérieure : Groupes de jetons qualifiés par nom de domaine
    • Versions d'AD FS antérieures à la version 5.0 : Groupes de jetons - Noms qualifiés

  6. Dans Type de revendication sortante, sélectionnez :

    • AD FS version 5.0 et ultérieure : Groupe
    • Versions d'AD FS antérieures à la version 5.0 : groupes

  7. Cliquez sur Terminer, puis sur Appliquer.

Enregistrer le plug-in Kubectl pour OIDC et la console Google Cloud avec AD FS

Ouvrez une fenêtre PowerShell en mode Administrateur, puis entrez la commande suivante :

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

où :

  • [CLIENT_ID] est l'ID client que vous avez obtenu précédemment.

  • [SERVER_ROLE_IDENTIFIER] est l'identifiant de revendication que vous avez saisi précédemment. Rappelez-vous que l'identifiant suggéré était token-groups-claim.

Remplir la spécification oidc dans le fichier de configuration du cluster

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 propres à votre fournisseur :

oidc:
  issuerurl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl : valeur 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 d'API Kubernetes utilise cette URL pour découvrir des clés publiques permettant de valider les jetons. Vous devez utiliser HTTPS.
  • clientid : valeur obligatoire. ID de l'application cliente qui envoie des requêtes d'authentification au fournisseur OpenID. Le plug-in Kubectl pour OIDC et la console Google Cloud utilisent tous deux cet ID.
  • clientsecret : facultatif. Code secret de l'application cliente. Le plug-in Kubectl pour OIDC et la console Google Cloud utilisent tous deux ce secret.
  • 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 de noms avec d'autres plug-ins.
  • usernameprefix : facultatif. Préfixe ajouté aux revendications de nom d'utilisateur pour éviter les conflits avec les noms existants. Si vous ne renseignez 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, pour un groupe foobar et un préfixe gid- donnés, 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 à l'agent Connect 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 stratégies 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 du 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 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 du 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 une virgule dans les requêtes 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 du 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 une virgule dans les requêtes 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 kubectl-oidc.exelogin 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 la console Google Cloud.

    Accéder à la page 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 la console Google Cloud à accéder à votre compte. Vous serez ensuite redirigé vers la page Clusters Kubernetes dans la console Google Cloud.

Résumé

Votre entreprise exécute un serveur AD FS qui fait office de fournisseur OpenID. Votre fournisseur OpenID connaît vos deux applications clientes : le plug-in Kubectl pour OIDC et la console Google Cloud. Votre fournisseur OpenID sait que vos applications clientes peuvent demander les champs d'application openid et allatclaims.

Dans la version d'AD FS antérieure à la version 5.0, l'attribut LDAP Token-Groups Qualified Names de votre base de données AD est mappé sur la revendication groups de votre fournisseur OpenID. Dans la version 5.0 et les versions ultérieures, l'attribut est Token-Groups Qualified by Domain name. Le fournisseur renvoie les jetons qui incluent l'ID de l'employé, l'identifiant de l'émetteur, la revendication openid et la revendication groups. La revendication groups (Group dans la version 5.0) répertorie les groupes de sécurité auxquels un employé appartient.

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

Configuration non valide

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

Configuration de fournisseur non valide

Si la configuration de votre fournisseur d'identité n'est pas valide, un message d'erreur en provenance de votre fournisseur d'identité s'affiche lorsque vous cliquez sur CONNEXION. Suivez les instructions propres au fournisseur pour configurer correctement le fournisseur ou votre cluster.

Autorisations non valides

Si vous avez terminé le processus d'authentification, mais que vous ne voyez toujours pas les détails du cluster, assurez-vous que vous avez accordé les autorisations RBAC correctes 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 à la console Google Cloud.

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

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

Étapes suivantes