Referenz zur SAML-Konfiguration

Informationen zur SAML-Konfiguration

Um SAML Single Sign-On (SSO) für die Authentifizierung zu GitHubverwenden, müssen Sie sowohl Ihren externen SAML-Identitätsanbieter (IdP) als Ihre GitHub Enterprise Server-Instancekonfigurieren. In einer SAML-Konfiguration GitHub fungiert sie als SAML-Dienstanbieter (SP). Weitere Informationen zur Authentifizierung für dein Unternehmen findest du unter Grundlagen der Identitäts- und Zugriffsverwaltung.

GitHub bietet die Integration gemäß der SAML 2.0-Spezifikation. Weitere Informationen findest du im SAML-Wiki auf der OASIS-Website.

Sie müssen eindeutige Werte aus Ihrem SAML-IdP eingeben, wenn Sie SAML SSO für GitHubkonfigurieren, und Sie müssen auch eindeutige Werte aus GitHub Ihrem IdP eingeben.

SAML-Metadaten

Die SP-Metadaten für Ihre GitHub Enterprise Server-Instance sind unter http(s)://HOSTNAME/saml/metadata verfügbar, wobei HOSTNAME der Hostname für Ihre Instanz ist. GitHub Enterprise Server verwendet die urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST Bindung.

Wert	Andere Namen	BESCHREIBUNG	Beispiel
Entitäts-ID des SP	SP-URL, Zielgruppeneinschränkung	Die URL der obersten Ebene für deine GitHub Enterprise Server-Instanz	http(s)://HOSTNAME
Assertionsverbraucherdienst-URL (ACS) des SP	Antwort-, Empfänger- oder Ziel-URL	URL, an die der IdP SAML-Antworten sendet	http(s)://HOSTNAME/saml/consume
SSO-URL (einmaliges Anmelden) des SP
URL, an der der IdP mit dem SSO-Prozess beginnt	http(s)://HOSTNAME/sso

SAML-Attribute

Die folgenden SAML-Attribute sind für GitHub. verfügbar. Mit Ausnahme des Verwaltungskonsole Attributs können Sie die Attributnamen im administratorAttribut ändern. Weitere Informationen finden Sie unter Verwalten Ihrer Instanz über die Web-Benutzeroberfläche.

Name	Erforderlich	BESCHREIBUNG
NameID		Ein persistenter Benutzerkennzeichner. Es kann ein beliebiges Format für persistente Namenskennzeichner verwendet werden.
GitHub das Element NameID zur Verwendung als Benutzername, sofern keine der alternativen Assertions bereitgestellt wird. Weitere Informationen finden Sie unter Überlegungen zum Benutzernamen für die externe Authentifizierung.

[!NOTE] Es ist wichtig, einen visuell lesbaren, beständigen Bezeichner zu verwenden. Die Verwendung eines vorübergehenden Bezeichnerformats urn:oasis:names:tc:SAML:2.0:nameid-format:transient führt dazu, dass Konten bei jeder Anmeldung erneut verknüpft werden, was sich nachteilig auf die Autorisierungsverwaltung auswirken kann. | | SessionNotOnOrAfter | | Das Datum, an dem GitHub die zugeordnete Sitzung ungültig macht. Nach der Ungültigheit muss sich die Person erneut authentifizieren, um auf die RessourcenIhre GitHub Enterprise Server-Instance Ihres Unternehmens zuzugreifen. Weitere Informationen findest du unter Sitzungsdauer und Timeout. | | | | administrator | | Wenn der Wert true ist, wird GitHub den Benutzer automatisch zum Websiteadministrator machen. Wenn das Attribut auf alles außer true festgelegt wird, folgt eine Herabstufung, solange der Wert nicht leer ist. Wenn das Attribut ausgelassen wird oder der Wert leer bleibt, wird die Rolle des Benutzers bzw. der Benutzerin nicht geändert. | | username | | Der Benutzername für Ihre GitHub Enterprise Server-Instance. | | | | full_name | | vollständige Name des Benutzers auf der Profilseite des Benutzers angezeigt. | | emails | | Die E-Mail-Adressen für den Benutzer. Sie können mehrere Adressen angeben. Wenn Sie die Lizenznutzung zwischen GitHub Enterprise Server und GitHub Enterprise Cloud synchronisieren, verwendet GitHub Connectemails, um eindeutige Benutzer produktübergreifend zu identifizieren. Weitere Informationen finden Sie unter Synchronisieren der Lizenznutzung von GitHub Enterprise Server in die Cloud. | | public_keys | | öffentlichen SSH-Schlüssel für den Benutzer. Du kannst mehr als einen Schlüssel angeben. | | gpg_keys | | GPG-Schlüssel für den Benutzer. Du kannst mehr als einen Schlüssel angeben. |

Verwende mehrere <saml2:AttributeValue>-Elemente, um mehrere Werte für ein Attribut anzugeben.

<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>

SAML-Antwortanforderungen

GitHub erfordert, dass die Antwortnachricht von Ihrem IdP die folgenden Anforderungen erfüllt.

• Dein IdP musst das Element <Destination> im Stammantwortdokument bereitstellen und nur dann mit der ACS-URL übereinstimmen, wenn das Stammantwortdokument signiert ist. Wenn Ihr IdP die Assertion signiert, ignoriert GitHub die Assertion.

• Dein IdP muss das <Audience>-Element immer als Teil des <AudienceRestriction>-Elements bereitstellen. Der Wert muss mit Ihrem EntityId für GitHub übereinstimmen. Dieser Wert ist die URL, unter der Sie auf GitHub zugreifen, wie z. B. http(s)://HOSTNAME.

• Dein IdP muss eine einzelne Assertion in der Antwort mit einer digitalen Signatur schützen. Hierfür kannst du das <Assertion>-Element oder das <Response>-Element signieren.

• Dein IdP muss ein <NameID>-Element als Teil des <Subject>-Elements bereitstellen. Du kannst ein beliebiges Format für beständige Namensbezeichner verwenden.

• Dein IdP muss das Recipient-Attribut enthalten, das auf die ACS-URL festgelegt werden muss. Im folgenden Beispiel wird das Attribut veranschaulicht.

  <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>
  

SAML-Signaturzertifikat für AuthnRequests

Wenn Sie GitHub Enterprise Server zum ersten Mal einrichten und die Instanz starten, wird ein selbstsigniertes SAML-Signaturzertifikat generiert, das vom SAML-Zertifikat des IdP getrennt ist. Dieses Zertifikat wird zum Signieren von SAML-AuthnRequests-Elementen verwendet, die an den IdP gesendet werden. Das Zertifikat ist für zehn Jahre gültig. Es wird unter /data/user/common/saml-sp.p12 gespeichert, und du kannst Details im Base64-codierten Format unter http(s)://HOSTNAME/saml/metadata anzeigen.

Wenn dein IdP das SAML-Signaturzertifikat überprüft oder SAML-verschlüsselte Assertionen aktiviert sind, treten bei Benutzenden möglicherweise Authentifizierungsprobleme auf, wenn das Zertifikat abläuft. Um das Ablaufdatum zu überprüfen, kann ein GitHub Enterprise Server Administrator über SSH eine Verbindung mit dem Server herstellen und den folgenden Befehl ausführen. Weitere Informationen findest du unter Herstellen einer Verbindung mit der Verwaltungsshell über SSH.

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

Um dieses SAML SP-Signaturzertifikat erneut zu generieren, wenn es abgelaufen ist und von idP oder verschlüsselten Assertionen benötigt wird, kann ein GitHub Enterprise Server Administrator die nachfolgenden Befehle in einer GitHub Enterprise Server SSH-Sitzung ausführen.

# 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

Sitzungsdauer und Timeout

Um zu verhindern, dass eine Person sich mit Ihrem IdP authentifiziert und auf unbestimmte Zeit autorisiert bleibt, GitHub wird die Sitzung für jedes Benutzerkonto mit Zugriff auf Ihre GitHub Enterprise Server-Instance Ihres Unternehmens regelmäßig ungültig. Nach der Invalidierung muss die Person sich erneut bei Ihrem IdP authentifizieren.

Wenn Ihr IdP einen Wert für das SessionNotOnOrAfter Attribut nicht bestätigt, GitHub wird eine Sitzung pro Woche nach erfolgreicher Authentifizierung mit Ihrem IdP ungültig.

GitHub unterstützt eine angepasste Sitzungsdauer, wenn Ihr IdP die Möglichkeit bietet, ein Attribut und einen SessionNotOnOrAfter Wert zu konfigurieren, und wenn dieses Attribut in SAML-Antworten enthalten ist. Wenn Ihr IdP kein SessionNotOnOrAfter Attribut zulässt, kann ein Websiteadministrator ein benutzerdefiniertes SAML-Sitzungstimeout für alle Benutzer in Ihrer Instanz mithilfe des ghe-config saml.default-session-expiration [seconds] Befehls in der Verwaltungsshell konfigurieren.

Wenn Sie eine benutzerdefinierte Sitzungsdauer von weniger als 24 Stunden festlegen, kann GitHub Benutzer dazu auffordern, sich jedes Mal zu authentifizieren, wenn GitHub eine Umleitung initiiert.

Unabhängig von der für deine Instanz verwendeten Authentifizierungsmethode beendet GitHub Enterprise Server eine Benutzersitzung nach zwei Wochen Inaktivität.