Référence de configuration SAML

À propos de la configuration SAML

Pour utiliser l’authentification unique (SSO) SAML pour vous authentifier auprès de GitHub, vous devez configurer à la fois votre fournisseur d’identité SAML externe (IdP) et votre instance GitHub Enterprise Server. Dans une configuration SAML, GitHub fonctionne en tant que fournisseur de services SAML (SP). Pour plus d'informations sur l'authentification pour votre entreprise, consultez « Notions de base de la gestion des identités et des accès ».

GitHub fournit une intégration en fonction de la spécification SAML 2.0. Pour plus d’informations, consultez le Wiki SAML sur le site web OASIS.

Vous devez saisir des valeurs uniques provenant de votre fournisseur d’identité SAML (IdP) lors de la configuration de l’authentification unique SAML pour GitHub, et vous devez également saisir des valeurs uniques provenant de GitHub sur votre IdP.

Métadonnées SAML

Les métadonnées votre instance GitHub Enterprise Server du fournisseur de services sont disponibles à l’emplacement http(s)://HOSTNAME/saml/metadata, où HOSTNAME est le nom d’hôte de votre instance. GitHub Enterprise Server utilise la liaison urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Valeur	Autres noms	Description	Exemple
ID d'entité SP	SP URL, restriction d'audience	URL de niveau supérieur pour votre instance GitHub Enterprise Server	http(s)://HOSTNAME
URL Assertion Consumer Service (ACS) du fournisseur de service	URL de réponse, de destinataire ou de destination	URL où l'IdP envoie des réponses SAML	http(s)://HOSTNAME/saml/consume
URL de SSO du fournisseur de services (SP)
URL à laquelle le fournisseur d’identité commence l’authentification unique	http(s)://HOSTNAME/sso

Attributs SAML

Les attributs SAML suivants sont disponibles pour GitHub. Vous pouvez modifier les noms d’attributs dans le Console de gestion, à l’exception de l’attribut administrator . Pour plus d’informations, consultez Géstion de votre instance à partir de l’IU WEB..

Nom	Obligatoire	Description
NameID		Identificateur d'utilisateur persistant. Il est possible d'utiliser n'importe quel format d'identificateur de nom persistant.
GitHub normalise l’élément NameID à utiliser comme nom d’utilisateur, sauf si l’une des autres assertions est fournie. Pour plus d’informations, consultez « Considérations relatives au nom d'utilisateur pour une authentification externe ».

[!NOTE] Il est important d’utiliser un identificateur explicite et persistant. L’utilisation d’un format d’identificateur temporaire comme urn:oasis:names:tc:SAML:2.0:nameid-format:transient entraîne une nouvelle liaison des comptes à chaque connexion, ce qui peut nuire à la gestion des autorisations. | | SessionNotOnOrAfter | | Date à laquelle GitHub invalide la session associée. Après l’invalidation, la personne doit s’authentifier une fois de plus pour accéder aux votre instance GitHub Enterprise Server de votre entreprise. Pour plus d’informations, consultez « Durée et délai d’expiration de session ». | | | | administrator | | Lorsque la valeur est true, GitHub promouvoira automatiquement l’utilisateur comme administrateur de site. La définition de cet attribut sur autre chose que true entraîne une rétrogradation, dans la mesure où la valeur n'est pas vide. Si cet attribut est omis ou que sa valeur reste vide, le rôle de l'utilisateur est inchangé. | | username | | Nom d’utilisateur pour votre instance GitHub Enterprise Server. | | | | full_name | | Le nom complet de l’utilisateur à afficher sur la page de profil de l’utilisateur. | | emails | | Adresses e-mail de l’utilisateur. Vous pouvez spécifier plusieurs adresses. Si vous synchronisez l’utilisation des licences entre GitHub Enterprise Server et GitHub Enterprise Cloud, GitHub Connect utilise emails pour identifier des utilisateurs uniques entre les produits. Pour plus d’informations, consultez « Synchronisation de l’utilisation des licences de GitHub Enterprise Server vers le cloud ». | | public_keys | | clés SSH publiques pour l’utilisateur. Vous pouvez spécifier plus d'une clé. | | gpg_keys | | clés GPG pour l’utilisateur. Vous pouvez spécifier plus d'une clé. |

Pour spécifier plusieurs valeurs pour un même attribut, utilisez plusieurs éléments <saml2:AttributeValue>.

<saml2:Attribute FriendlyName="public_keys" Name="urn:oid:1.2.840.113549.1.1.1" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml2:AttributeValue>ssh-rsa LONG KEY</saml2:AttributeValue>
    <saml2:AttributeValue>ssh-rsa LONG KEY 2</saml2:AttributeValue>
</saml2:Attribute>

Exigences en matière de réponse SAML

GitHub exige que le message de réponse de votre fournisseur d’identité réponde aux exigences suivantes.

• Votre IdP doit fournir l'élément <Destination> dans le document de réponse racine et correspondre à l'URL ACS uniquement lorsque le document de réponse racine est signé. Si votre IdP signe l’assertion, GitHub ignorera l’assertion.

• Votre fournisseur d'identité doit toujours fournir l'élément <Audience> dans le cadre de l'élément <AudienceRestriction>. La valeur doit correspondre à votre EntityId pour GitHub. Cette valeur est l’URL à laquelle vous accédez à GitHub, par exemple http(s)://HOSTNAME.

• Votre IdP doit fournir une unique assertion dans la réponse, accompagnée d’une signature numérique. Vous pouvez accomplir cela en signant l’élément <Assertion> ou en signant l’élément <Response>.

• Votre fournisseur d'identité doit fournir un élément <NameID> dans le cadre de l'élément <Subject>. Vous pouvez utiliser n'importe quel format d'identificateur de nom persistant.

• Votre fournisseur d’identité doit inclure l’attribut Recipient, qui doit être défini sur l’URL ACS. L'exemple suivant illustre l'attribut.

  <samlp:Response ...>
    <saml:Assertion ...>
      <saml:Subject>
        <saml:NameID ...>...</saml:NameID>
        <saml:SubjectConfirmation ...>
          <saml:SubjectConfirmationData Recipient="https://HOSTNAME/saml/consume" .../>
        </saml:SubjectConfirmation>
      </saml:Subject>
      <saml:AttributeStatement>
        <saml:Attribute FriendlyName="USERNAME-ATTRIBUTE" ...>
          <saml:AttributeValue>monalisa</saml:AttributeValue>
        </saml:Attribute>
      </saml:AttributeStatement>
    </saml:Assertion>
  </samlp:Response>
  

Certificat de signature SAML pour AuthnRequests

Lorsque vous configurez GitHub Enterprise Server et démarrez l’instance, un certificat de signature SAML auto-signé est généré, distinct du certificat SAML du fournisseur d’identité. Ce certificat sert à signer le SAML AuthnRequests transmis à l’IdP et demeure valide pendant une durée de dix ans. Il est stocké à /data/user/common/saml-sp.p12 et vous pouvez consulter les détails au format encodé en base64 à l'adresse suivante http(s)://HOSTNAME/saml/metadata.

Si votre fournisseur d'identité valide le certificat de signature SAML, ou si les assertions chiffrées SAML sont activées, les utilisateurs peuvent rencontrer des problèmes d'authentification lorsque le certificat expire. Pour vérifier la date d’expiration, un GitHub Enterprise Server administrateur peut se connecter au serveur via SSH et exécuter la commande ci-dessous. Voir Connexion au shell administratif via SSH.

sudo openssl pkcs12 -in /data/user/common/saml-sp.p12 -clcerts -nokeys -password pass: | sudo openssl x509 -noout -enddate

Pour régénérer ce certificat de signature du SP SAML s’il a expiré et s’il est requis par l’IdP ou pour les assertions chiffrées, un administrateur GitHub Enterprise Server peut exécuter les commandes ci-dessous dans une GitHub Enterprise Server session SSH.

# Backup the old certificate
sudo cp /data/user/common/saml-sp.p12 /data/user/common/saml-sp.p12-$(date +%d%m%Y_%H%M%S)

saml_tempdir=$(sudo mktemp -d)
sudo openssl req -new -newkey rsa:4096 -days 3650 -nodes -x509 -sha256 -subj "/CN=github_enterprise" -keyout $saml_tempdir/saml.key -out $saml_tempdir/saml.crt
sudo openssl pkcs12 -export -inkey $saml_tempdir/saml.key -in $saml_tempdir/saml.crt -nodes -password pass: -out /data/user/common/saml-sp.p12
sudo rm -rf $saml_tempdir

sudo nomad stop github-unicorn
sudo nomad run -hcl1 /etc/nomad-jobs/github/unicorn.hcl

Durée et délai d'expiration de session

Pour empêcher une personne de s’authentifier auprès de votre IdP et de rester autorisée indéfiniment, GitHub invalide régulièrement la session de chaque compte d’utilisateur ayant accès aux votre instance GitHub Enterprise Server. Après l’invalidation, la personne doit s’authentifier à nouveau auprès de votre fournisseur d’identité.

Par défaut, si votre fournisseur d’identité n’affirme pas de valeur pour l’attribut SessionNotOnOrAfter , GitHub invalide une session une semaine après l’authentification réussie avec votre fournisseur d’identité.

GitHub prend en charge une durée de session personnalisée si votre IdP permet de configurer un SessionNotOnOrAfter attribut et une valeur, et si cet attribut est inclus dans les réponses SAML. Si votre fournisseur d’identité ne permet pas d’utiliser l’attribut SessionNotOnOrAfter, un administrateur de site peut configurer un délai d’expiration de session SAML personnalisé pour tous les utilisateurs de votre instance à l’aide de la commande ghe-config saml.default-session-expiration [seconds] dans le shell d’administration.

Si vous définissez une valeur de durée de session personnalisée inférieure à 24 heures, GitHub vous pouvez inviter des personnes à s’authentifier chaque fois qu’une GitHub redirection est lancée.

Quelle que soit la méthode d’authentification utilisée sur votre instance, GitHub Enterprise Server termine une session utilisateur après deux semaines continues d’inactivité.