Configuration de l’authentification et de l’approvisionnement avec PingFederate

Lorsque vous utilisez un IdP pour IAM sur GitHub Enterprise Server, SAML SSO contrôle et sécurise l'accès aux ressources de l'entreprise telles que les référentiels, les issues et les requêtes de tirage. SCIM crée automatiquement des comptes d'utilisateurs et gère l'accès à votre entreprise lorsque vous apportez des modifications à votre IdP. Vous pouvez également synchroniser les équipes sur GitHub avec les groupes sur votre IdP. Pour plus d’informations, consultez À propos de l’approvisionnement d’utilisateurs avec SCIM sur GitHub Enterprise Server.

Vue d’ensemble

Ce guide vous aide à configurer l’authentification SAML et l’approvisionnement SCIM pour GitHub sur PingFederate.

Avant de commencer, notez les points suivants :

• L’utilisation de PingFederate en tant qu’IdP pour GitHub Enterprise Server est proposée en préversion publique. Contactez l’équipe de votre compte pour fournir des commentaires.
• Ce guide est basé sur PingFederate version 12.1. Les instructions peuvent varier pour d’autres versions.
• Ce guide fournit les étapes minimales pour mettre en place une configuration fonctionnelle. Étant donné que votre répertoire d’identité peut être connecté à PingFederate différemment, vous devez choisir les attributs de données appropriés pour SAML et SCIM en fonction de ce qui est disponible à partir de votre magasin de données de sauvegarde.

Prérequis

Les conditions générales d'utilisation de SCIM sur GitHub Enterprise Server s'appliquent. Consultez la section « Conditions préalables » dans Configuration du provisionnement SCIM pour gérer les utilisateurs.

De plus :

• Pour configurer SCIM, vous devez avoir effectué les étapes 1 à 4 dans Configuration du provisionnement SCIM pour gérer les utilisateurs.
  • Vous aurez besoin du personal access token (classic) créé pour l’utilisateur de configuration afin d’authentifier les requêtes envoyées depuis PingFederate.
• Vous devez avoir installé le « connecteur GITHUB UEM » sur PingFederate. Pour télécharger et installer le connecteur, consultez Installer le provisionneur dans la documentation PingIdentity.
• Pour approvisionner des utilisateurs avec SCIM, vous devez utiliser un serveur LDAP comme magasin de données de stockage.
• Il peut être nécessaire de configurer le pare-feu dans PingFederate afin d’autoriser les connexions sortantes vers le point de terminaison https://HOSTNAME/api/v3/scim/v2 de votre instance GitHub Enterprise Server.
• Le « mode d’approvisionnement » de PingFederate doit être défini sur une valeur qui autorise l’approvisionnement SCIM. Consultez la section « Avant de commencer » dans le guide Paramètres d’approvisionnement sortant de PingIdentity.
• Au cours de cette procédure, vous devez charger un certificat X509 sur PingFederate. Vous pouvez créer et stocker le certificat avant de continuer. Vous aurez également besoin du mot de passe de défi pour le certificat. Consultez la section Exemple de création d’un certificat X509 plus loin dans cet article.

1. Configuration de SAML

Dans cette section, vous allez créer un connecteur SAML dans PingFederate, configurer une instance d’adaptateur IdP LDAP et gérer la sortie SAML à partir de votre adaptateur IdP.

1.        [Créer un adaptateur SAML](#create-a-saml-adapter)
   

2.        [Configurer une instance d’adaptateur IdP LDAP](#set-up-an-ldap-idp-adapter-instance)
   

3.        [Gérer la sortie SAML à partir de votre adaptateur IdP](#manage-saml-output-from-your-idp-adapter)
   

Avant de commencer cette section, vérifiez que vous avez suivi les étapes 1 et 2 dans Configuration du provisionnement SCIM pour gérer les utilisateurs.

Créer un adaptateur SAML

1. Ouvrez la console d’administration PingFederate.

2. Cliquez sur Applications dans l’en-tête, puis sur Connexions SP dans la barre latérale gauche.

3. Cliquez sur Utilisez un modèle pour cette connexion, puis sélectionnez le « connecteur GITHUB UEM » dans la liste déroulante « Modèle de connexion ».

   Remarque

   Si vous ne voyez pas cette option, le connecteur GITHUB UEM n'a pas été installé. Si vous avez besoin d’aide, contactez votre représentant Ping.

4. Pour remplir certains champs dans la configuration de PingFederate, vous allez charger un fichier XML contenant des métadonnées SAML pour votre entreprise.

   1. Dans un nouvel onglet, connectez-vous à GitHub en tant qu’utilisateur de configuration intégré. Accédez à votre page de métadonnées SAML à https://HOSTNAME/saml/metadata.
   2. Téléchargez la page en tant que fichier XML.

5. Sur la page PingFederate « Connexion SP », chargez le fichier à partir de l’étape précédente en tant que fichier de métadonnées. Veillez à le faire dans les 5 minutes suivant le téléchargement du fichier.

6. Accédez à l’onglet « Type de connexion ».

7. Sélectionnez Profils SSO du navigateur et désélectionnez Approvisionnement sortant (cette option sera activée ultérieurement).

8. Cliquez sur Suivant.

9. Sous l’onglet « Options de connexion », vérifiez que seul SSO du navigateur est sélectionné.

10. Cliquez sur Suivant.

11. Dans l’onglet « Informations générales », saisissez les détails suivants.

    • « ID d’entité du partenaire » : votre URL hôte GitHub (https://HOSTNAME.com)
    • « Nom de la connexion » : nom descriptif de votre connexion SP dans PingFederate
    • « URL de base » : URL de l'hôte de votre GitHub (https://HOSTNAME.com)
    • « Journalisation des transactions » : standard
    • Tous les autres champs peuvent rester vides.

12. Cliquez sur Suivant.

13. Cliquez sur Configurer SSO du navigateur.

14. Cliquez sur Configurer la création d’assertions.

15. Sous l’onglet « Mappage de source d’authentification », cliquez sur Mapper une nouvelle instance d’adaptateur.

16. Sous l’onglet « Instance d’adaptateur », cliquez sur Gérer les instances d’adaptateur.

17. Cliquez sur Créer une nouvelle instance.

Configurer une instance d’adaptateur IdP LDAP

1. Dans la page « Créer une instance d’adaptateur » de PingFederate, sous l’onglet « Type », saisissez les détails suivants.

   • « Nom de l’instance » : nom permettant d’identifier l’instance, par exemple pfghadapter
   • « ID de l’instance » : ID de l’instance, par exemple pfghadapter
   • « Type » : adaptateur IDP de formulaire HTML
   • « Instance parent » : aucune

2. Cliquez sur Suivant.

3. Sous l’onglet « Adaptateur IDP », en bas de la page, cliquez sur Gérer les validateurs d’informations d’identification du mot de passe.

4. Cliquez sur Créer une nouvelle instance.

5. Dans l’onglet « Type », saisissez les informations suivantes.

   • « Nom de l’instance » : nom permettant d’identifier l’instance, par exemple pfghdocscv
   • « ID de l’instance » : ID de l’instance, par exemple pfghdocscv
   • « Type » : validateur d’informations d’identification du mot de passe du nom d’utilisateur LDAP
   • « Instance parent » : aucune

6. Cliquez sur Suivant.

7. Dans l’onglet « Configuration de l’instance », cliquez sur Gérer les magasins de données.

8. Cliquez sur Ajouter un nouveau magasin de données.

9. Dans l’onglet « Type de magasin de données », saisissez les informations suivantes.

   • « Nom de l’instance » : toute valeur unique, telle que pfghdocsds
   • « Type » : annuaire (LDAP)
   • « Masquer les valeurs dans le journal » : désélectionné

10. Cliquez sur Suivant.

11. Dans l’onglet « Configuration LDAP », configurez les détails de votre serveur LDAP.

12. Cliquez sur Tester la connexion. Vous devriez voir « Le test de connectivité a réussi ».

13. Au bas de la page, cliquez sur Avancé.

14. Cliquez sur l’onglet « Attributs binaires LDAP », puis ajoutez guidAttribute et objectGUID en tant qu’attributs.

15. Cliquez sur Done. Vous devez revenir à l’onglet « Configuration LDAP ».

16. Cliquez sur Suivant et sur Enregistrer.

17. Dans l’onglet « Gérer les magasins de données », cliquez sur Terminé.

18. Dans l’onglet « Configuration de l’instance », saisissez les informations suivantes.

    • « Magasin de données LDAP » : nom du magasin de données que vous avez créé ci-dessus
    • « Base de recherche » : emplacement dans l’annuaire dans lequel vous souhaitez que les recherches LDAP commencent
    • « Filtre de recherche » : filtre qui garantit que le nom d’utilisateur saisi par l’utilisateur lors de la connexion correspond à un champ du serveur LDAP (par exemple : sAMAccountName=${username})
    • « Étendue de la recherche » : sous-arbre
    • « Correspondance sensible à la casse » : sélectionnée

19. Cliquez sur Suivant, encore Suivant, puis Enregistrer.

Gérer la sortie SAML à partir de votre adaptateur IdP

1. Dans la page « Gérer les validateurs d’informations d’identification du mot de passe », cliquez sur Terminé.

2. Dans l’onglet « Adaptateur IDP », saisissez les informations suivantes.

   • « Instance de validateur d’informations d’identification du mot de passe » : le nom de l’instance du validateur que vous avez créée ci-dessus (par exemple pfghdocscv). Cliquez sur Mettre à jour pour finaliser votre sélection.
   • Tous les autres champs peuvent être laissés comme valeurs par défaut ou modifiés en fonction de vos besoins.

3. Cliquez sur Suivant, puis encore sur Suivant.

4. Dans l’onglet « Attributs de l’adaptateur », saisissez les informations suivantes.

   • « Attribut clé utilisateur unique » : username

   • À côté de l’attribut username, sélectionnez « Pseudonyme ».

   Remarque

   Cette étape est importante. L’attribut de l’adaptateur est utilisé pour identifier de manière unique un utilisateur sur GitHub lors de l’approvisionnement SCIM.

5. Cliquez sur Suivant, puis encore sur Suivant.

6. Vérifiez vos paramètres sur la page de résumé, puis cliquez sur Enregistrer.

7. Sous l’onglet « Adaptateurs IdP », vous devez voir l’adaptateur que vous venez de créer. Cliquez sur Done.

8. Sous l’onglet « Instance d’adaptateur », dans la liste déroulante « Instance d’adaptateur », sélectionnez l’adaptateur que vous venez de créer.

9. Cliquez sur Suivant.

10. Sous l’onglet « Méthode de mappage », sélectionnez Utiliser uniquement les valeurs du contrat d’adaptateur dans l’assertion SAML (d’autres sélections peuvent fonctionner, mais n’ont pas été confirmées).

11. Cliquez sur Suivant.

12. Sous l’onglet « Traitement du contrat d’attribut », associez SAML_SUBJECT à « Adaptateur » comme source et username comme valeur.

    Remarque

    Cette étape est importante. Le SAML_SUBJECT normalisé doit correspondre aux noms d’utilisateur normalisés des utilisateurs approvisionnés par SCIM.

13. Cliquez sur Suivant, encore sur Suivant, puis sur Enregistrer.

14. Vous devez revenir à l’onglet « Mappage de source d’authentification » et la section « Nom de l’instance de l’adaptateur » doit contenir l’instance de l’adaptateur que vous venez de créer.

15. Cliquez sur Suivant.

16. Sous l’onglet « Paramètres du protocole », cliquez sur Configurer les paramètres du protocole.

17. Pour l’« URL du service consommateur d’assertion », ajoutez une ligne avec les informations suivantes :

    • «Par défaut» sélectionné
    • « Index » : 0
    • « Liaison » : POST
    • « URL du point de terminaison » : HOSTNAME/saml/consume

18. Cliquez sur Suivant.

19. Sous l’onglet « Liaisons SAML autorisées », vérifiez que seuls « POST » et « REDIRECT » sont sélectionnés.

20. Cliquez sur Suivant.

21. Dans la page « Stratégie de signature », vérifiez que seule l’option « SIGNER LA RÉPONSE SELON LES EXIGENCES » est cochée.

22. Cliquez sur Suivant.

23. Sous l’onglet « Azure Policy de chiffrement », vérifiez que « NONE » est sélectionné.

24. Cliquez sur Suivant.

25. Cliquez sur Enregistrer.

26. Cliquez sur Suivant et sur Terminé jusqu’à atteindre l’onglet « Informations d’identification ».

27. Sous l’onglet « Informations d’identification », cliquez sur Configurer les informations d’identification, puis sur Gérer les certificats.

28. Dans la page « Gestion des certificats », cliquez sur Importer, puis chargez un certificat X509 (pour obtenir de l’aide, consultez la section Exemple de création d’un certificat X509).

29. Pour le « Mot de passe », utilisez le mot de passe de défi pour le certificat.

30. Cliquez sur Suivant et sur Enregistrer.

31. Dans l’onglet « Gestion des certificats », vous devez voir le certificat que vous venez d’importer. Cliquez sur Done.

32. Dans l’onglet « Paramètres de signature numérique » :

    • Sélectionnez le certificat que vous venez de créer pour le « Certificat de signature ».
    • Vous pouvez laisser le certificat secondaire vide et la case à cocher « Inclure le certificat dans la signature » est désactivée.
    • L’algorithme de signature doit être « RSA SHA256 ».

33. Cliquez sur Suivant, ensuite sur Enregistrer, puis sur Suivant.

34. Dans l’onglet « Résumé », activez le bouton bascule pour « Point de terminaison d’application SSO ».

35. Cliquez sur Enregistrer. Vous devez revenir à la liste des connexions SP, où vous devez voir votre connexion SP nouvellement créée.

Collecter des informations pour votre configuration SAML

Vous aurez besoin de détails de PingFederate pour configurer SAML sur GitHub.

1. Dans la page « Connexions du fournisseur de services », dans la ligne de votre nouvelle connexion, cliquez sur Sélectionner une action, puis Exporter les métadonnées.
2. Sous l’onglet « Signature des métadonnées », dans la ligne de votre nouvelle connexion, sélectionnez le certificat de signature que vous avez créé ci-dessus. Pour télécharger le certificat, cliquez sur Suivant, puis sur Exporter.
3. Sur PingFederate, cliquez sur Système dans l’en-tête, puis sur Serveur, ensuite sur Paramètres du protocole. Vérifiez que la valeur SAML 2.0 ENTITY ID est définie. Notez-les, car vous en aurez besoin pour le champ « Émetteur » dans les paramètres SAML de GitHub.
4. Ouvrez le fichier de métadonnées que vous avez téléchargé et préparez-le pour les étapes suivantes.

Configurez GitHub

1. Connectez-vous à GitHub en tant que un utilisateur ayant accès à la console de gestion.

2. Activez SAML dans vos paramètres d’entreprise. Consultez Configuration d'une authentification unique (SSO) SAML pour votre entreprise.

3. Saisissez les valeurs suivantes du fichier de métadonnées SAML de la section précédente.

   • Pour l’URL d’authentification unique, utilisez la valeur location du champ <md: SingleSignOnService>. Il doit s’agir d’une URL se terminant par /idp/SSO.saml2.
   • Pour « Emetteur », utilisez la valeur entityId du champ <md: EntityDescriptor> (une URL).

4. Pour le « certificat de vérification », chargez le fichier de certificat X509 que vous avez créé précédemment.

5. Cliquez sur Enregistrer les paramètres.

2. Configurer SCIM

Dans cette section, vous allez configurer les paramètres SCIM et le mappage d’attributs sur PingFederate.

1.        [Configurer les paramètres SCIM](#configure-scim-settings)
   

2.        [Mapper des champs LDAP à SCIM](#map-ldap-fields-to-scim)
   

3.        [Terminer la configuration et le test](#finish-configuration-and-test)
   

Avant de commencer cette section, vérifiez que vous avez suivi les étapes 1 et 4 dans Configuration du provisionnement SCIM pour gérer les utilisateurs.

Configurer les paramètres SCIM

1. Revenez à la page « Connexions SP » sur PingFederate, puis sélectionnez la connexion SP que vous avez créée précédemment.

2. Cliquez sur l’onglet « Type de connexion ».

3. Sélectionnez Approvisionnement sortant.

4. Vérifiez que les Profils SSO du navigateur sont sélectionnés.

5. Cliquez sur Suivant jusqu’à atteindre l’onglet « Approvisionnement sortant », puis cliquez sur Configurer l’approvisionnement.

6. Saisissez les informations suivantes sous l’onglet « Objectif ».

   • « URL de base » : https://HOSTNAME/api/v3/scim/v2
   • « Jeton d’accès » : le personal access token (classic) créé pour l’utilisateur de configuration

7. Cliquez sur Suivant.

8. Dans l’onglet « Gérer le canal », cliquez sur Créer, puis saisissez un nom de canal unique, tel que pfghscim.

9. Cliquez sur Suivant.

10. Dans l’onglet « Source », sélectionnez le magasin de données que vous avez créé précédemment.

11. Cliquez sur Suivant.

12. Sous l’onglet « Paramètres sources », vous pouvez conserver tous les paramètres par défaut. D’autres paramètres sont susceptibles de fonctionner, mais n’ont pas été confirmés.

13. Cliquez sur Suivant.

14. Sous l’onglet « Emplacement source », configurez l’emplacement à partir duquel vous souhaitez que les utilisateurs approvisionnés proviennent de votre serveur LDAP. Cela varie en fonction de votre configuration et de vos besoins. Après la configuration, cliquez sur Suivant.

Associer des champs LDAP à SCIM

Sous l’onglet « Mappage d’attributs », vous devez mapper des champs de votre serveur LDAP aux champs SCIM. Consultez la liste suivante pour les champs SCIM pris en charge par GitHub et les valeurs attendues dans chacune d’elles.

• Nom d’utilisateur : celui-ci sera normalisé et utilisé comme nom d’utilisateur de GitHub pour l’utilisateur approvisionné. Consultez « Considérations relatives au nom d'utilisateur pour une authentification externe ». Cela doit correspondre à la normalisation de l’objet envoyé avec l’assertion SAML que vous avez configurée avec la propriété SAML_SUBJECT dans PingFederate.
• E-mail : champ contenant l’adresse e-mail de l’utilisateur.
• Nom à afficher : Un nom lisible par l'utilisateur.
• Nom complet formaté : le nom complet de l’utilisateur, y compris tous les deuxièmes prénoms, titres et suffixes, formaté pour l’affichage.
• Prénom : le prénom de l’utilisateur.
• Nom de famille : le nom de famille de l’utilisateur.
• Identificateur externe : cet identificateur est généré par un fournisseur IdP.
• Roles : ce champ doit contenir une chaîne qui représente le rôle prévu de l’utilisateur sur GitHub. Les rôles valides sont enterprise_owner et user.

Une fois terminée la configuration des paramètres, cliquez sur Suivant.

Terminer la configuration et le test

1. Dans l’onglet « Activation et résumé », pour « État de la chaîne », sélectionnez Actif.
2. Dans l’onglet « Gérer les canaux », cliquez sur Terminé.
3. Dans l’onglet « Approvisionnement sortant », cliquez sur Enregistrer. SCIM est maintenant configuré et activé.
4. Attendez quelques minutes pour que l’approvisionnement s’exécute, puis ouvrez une nouvelle fenêtre de navigateur privé et accédez à GitHub.
5. Cliquez sur Se connecter avec SAML. Vous devez être redirigé vers la page de connexion PingFederate.
6. Vous devez être en mesure de vous connecter avec les informations d’identification d’un utilisateur du serveur LDAP qui a été approvisionné sur GitHub.

L’approvisionnement PingFederate gère les utilisateurs et les groupes indépendamment. Les utilisateurs doivent être affectés directement pour être approvisionnés. Les utilisateurs qui se trouvent dans un groupe affecté, mais qui ne sont pas directement affectés ne seront pas approvisionnés.

Une fois que vous avez terminé de configurer SCIM, vous pouvez désactiver certains paramètres SAML que vous avez activés pour le processus de configuration. Consultez « Configuration du provisionnement SCIM pour gérer les utilisateurs ».

Exemple de création d’un certificat X509

Il existe plusieurs façons de créer un certificat X509. Voici un exemple qui peut fonctionner pour vos besoins.

1. Dans une fenêtre de terminal, vérifiez qu’OpenSSL est installé en exécutant openssl version. Si l’extension n’est pas installée, installez-la.

2. Générez la clé privée à l’aide de la commande suivante.

   Shell

   openssl req -nodes -sha256 -newkey rsa:2048 -keyout MyPrivateKey.key -out MyCertificateRequest.csr
   

   Saisissez les informations requises et prenez note du mot de passe de défi que vous créez.

3. Pour vous assurer que la clé a été créée, exécutez la commande suivante. Un fichier nommé MyPrivateKey.key doit être répertorié dans la sortie de commande.

   Shell

   ls | grep MyPrivateKey.key
   

4. Générez le certificat à l’aide de la commande suivante.

   Shell

   openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt
   

5. Pour vous assurer que le certificat a été créé, exécutez la commande suivante. Un fichier nommé pfgh256.crt doit être répertorié dans la sortie de commande.

   Shell

   ls | grep pfgh256.crt
   

6. Exportez un fichier PKCS #12 à l’aide de la commande suivante. Il s’agit du fichier que vous devez charger sur PingFederate.

   Shell

   openssl pkcs12 -export -in pfgh256.crt -inkey MyPrivateKey.key -out pfgh256.p12
   

7. Pour vous assurer que le fichier a été exporté, exécutez la commande suivante. Un fichier nommé pfgh256.p12 doit être répertorié dans la sortie de commande.

   Shell

   ls | grep pfgh256.p12