SAML verwenden

Wenn Du Benutzer authentifizieren möchtest, ohne sie Deinem Identitätsanbieter hinzuzufügen, kannst Du die integrierte Authentifizierung konfigurieren. Weitere Informationen finden Sie unter „Integrierte Authentifizierung für Benutzer außerhalb Ihres Identity Providers zulassen“.

Unterstützte SAML-Dienste

Wir bieten begrenzten Support für alle Identitätsanbieter, die den SAML 2.0 Standard implementieren. Offiziell unterstützen wir diese Identitätsanbieter, welche intern getestet wurden:

• Active Directory Federation Services (AD FS)
• Azure Active Directory (Azure AD)
• Okta
• OneLogin
• PingOne
• Shibboleth

GitHub Enterprise Server unterstützt keinen SAML Single-Logout. Um eine aktive SAML-Sitzung zu beenden, sollte sich der Benutzer direkt auf Deiner SAML-IdP abmelden.

Grundlegendes für Benutzernamen bei SAML

Jeder GitHub Enterprise Server-Benutzername wird nach Priorität geordnet durch eine der folgenden Assertions in der SAML-Antwort bestimmt:

• das benutzerdefinierte Attribut für den Benutzernamen, sofern definiert und vorhanden
• eine ggf. vorhandene Assertion http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
• eine ggf. vorhandene Assertion http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
• das Element NameID

Das Element NameID ist selbst dann erforderlich, wenn andere Attribute vorhanden sind.

A mapping is created between the NameID and the GitHub Enterprise Server username, so the NameID should be persistent, unique, and not subject to change for the lifecycle of the user.

GitHub Enterprise Server-Benutzernamen dürfen nur alphanumerische Zeichen und Bindestriche (-) enthalten. GitHub Enterprise Server normalisiert nicht alphanumerische Zeichen im Benutzernamen Ihres Kontos zu einem Bindestrich. Beispielsweise wird der Benutzername gregory.st.john zu gregory-st-john normalisiert. Beachte, dass die normalisierten Benutzernamen weder mit einem Bindestrich beginnen noch darauf enden können. Darüber hinaus können sie nicht zwei aufeinanderfolgende Bindestriche enthalten.

Anhand von E-Mail-Adressen erstellte Benutzernamen werden anhand der normalisierten Zeichen erstellt, die dem Zeichen @ vorangehen.

Wenn mehrere Konten zum selben GitHub Enterprise Server-Benutzernamen normalisiert werden, wird nur das erste Benutzerkonto erstellt. Nachfolgende Benutzer mit demselben Benutzernamen können sich nicht anmelden.

In dieser Tabelle findest Du Beispiele dafür, wie Benutzernamen in GitHub Enterprise Server normalisiert werden:

Zwei-Faktor-Authentifizierung

Bei Verwendung von SAML oder CAS wird die Zwei-Faktor-Authentifizierung auf der GitHub Enterprise Server-Appliance weder unterstützt noch verwaltet, jedoch möglicherweise vom externen Authentifizierungsanbieter unterstützt. Die Erzwingung der Zwei-Faktor-Authentifizierung für Organisationen ist nicht verfügbar. Weitere Informationen zum Erzwingen der Zwei-Faktor-Authentifizierung für Organisationen findest Du unter „Zwei-Faktor-Authentifizierung in Deiner Organisation vorschreiben.“

SAML-Metadaten

Die Service Provider-Metadaten Ihrer GitHub Enterprise Server-Instanzen sind unter http(s)://[hostname]/saml/metadata verfügbar.

Wenn Sie Ihren Identity Provider manuell konfigurieren möchten, lautet die Assertionsverbraucherdienst-URL (ACS) http(s)://[hostname]/saml/consume. Dafür wird die Bindung urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST verwendet.

SAML-Attribute

Die folgenden Attribute sind verfügbar. Mit Ausnahme der administrator-Attribute können Sie die Attributnamen in der Managementkonsole ändern.

SAML-Einstellungen konfigurieren

1. From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page.

   

2. Klicke auf der linken Seitenleiste auf Managementkonsole.

   

3. Klicke auf der linken Seitenleiste auf Authentication (Authentifizierung).

   

4. Wählen Sie SAML aus.

   

5. Wähle optional Allow built-in authentication (Integrierte Authentifizierung zulassen) um Benutzer zur Verwendung der integrierten Authentifizierung einzuladen, wenn sie nicht zum Identitätsanbieter von your GitHub Enterprise Server instance gehören.

   

6. Wählen Sie optional zum Aktivieren des Unsolicited-Response-SSOs die Option IdP initiated SSO (IdP-initiiertes SSO) aus. GitHub Enterprise Server antwortet auf eine von einem Identity Provider (IdP) initiierte unaufgeforderte Anforderung standardmäßig durch das Zurücksenden einer AuthnRequest an den IdP.

   

   Hinweis: Der Wert sollte bei unselected (Nicht ausgewählt) belassen werden. Sie sollten dieses Feature nur dann aktivieren, wenn Ihre SAML-Implementierung das vom Service Provider initiierte SSO nicht unterstützt und Sie vom GitHub Enterprise-Support dazu angewiesen werden.

7. Wählen Sie Disable administrator demotion/promotion (Hochstufen/Zurücksetzen des Administrators deaktivieren) aus, wenn Sie nicht möchten, dass Ihr SAML-Anbieter die Administratorrechte für Benutzer auf your GitHub Enterprise Server instance bestimmen kann.

   

8. Geben Sie im Feld Single sign-on URL (Single Sign-On-URL) den HTTP- oder HTTPS-Endpunkt für Ihren IdP für Single Sign-On-Anforderungen ein. Dieser Wert wird durch Ihre IdP-Konfiguration angegeben. Wenn der Host in Ihrem internen Netzwerk nicht verfügbar ist, müssen Sie your GitHub Enterprise Server instance ggf. zur Verwendung interner Nameserver konfigurieren.

   

9. Gib optional im Feld Issuer (Aussteller) den Namen Deines SAML-Ausstellers ein. Dadurch wird die Authentizität von Nachrichten verifiziert, die an your GitHub Enterprise Server instance gesendet werden.

   

10. Wählen Sie in den Dropdownmenüs Signature Method (Signaturmethode) und Digest Method (Digest-Methode) den von Ihrem SAML-Aussteller verwendeten Hashalgorithmus aus, um die Integrität der Anforderungen von your GitHub Enterprise Server instance zu verifizieren. Geben Sie das Format mit dem Dropdownmenü Name Identifier Format (Format für Namenskennzeichner) an.

    

11. Klicken Sie unter Verification certificate (Verifizierungszertifikat) auf Choose File (Datei auswählen), und wählen Sie ein Zertifikat aus, um Ihre SAML-Antworten vom IdP zu validieren.

    

12. Ändern Sie die SAML-Attributnamen bei Bedarf so, dass sie mit Ihrem IdP übereinstimmen, oder akzeptieren Sie die Standardnamen.

    

Zugriff auf your GitHub Enterprise Server instance widerrufen

Wenn Sie einen Benutzer von Ihrem Identity Provider entfernen, müssen Sie ihn zudem manuell sperren. Andernfalls kann er sich weiterhin mithilfe der Zugriffstoken oder SSH-Schlüssel authentifizieren. Weitere Informationen finden Sie unter „Benutzer sperren und entsperren“.

Anforderungen für die Antwortmeldung

Die Antwortmeldung muss die folgenden Anforderungen erfüllen:

• Das Element <Destination> muss im Root-Antwortdokument bereitgestellt werden und mit der ACS-URL übereinstimmen, und zwar genau dann, wenn das Root-Antwortdokument signiert ist. If the assertion is signed, it will be ignored.
• Das Element <Audience> muss immer als Bestandteil des Elements <AudienceRestriction> angegeben werden. Das Element <Audience> muss immer als Bestandteil des Elements <AudienceRestriction> angegeben werden. Dies ist die URL der GitHub Enterprise Server-Instanz, wie z.B.https://ghe.corp.example.com.
• Jede Assertion in der Antwort muss durch eine digitale Signatur geschützt sein. Dies kann erfolgen, indem jedes einzelne <Assertion>-Element signiert wird oder indem das <Response>-Element signiert wird.
• Ein <NameID>-Element muss als Bestandteil des <Subject>-Elements bereitgestellt werden. Es kann ein beliebiges Format für persistente Namenskennzeichner verwendet werden.
• Ein Recipient-Attribut muss vorhanden und auf die Assertionsverbraucherdienst-URL festgelegt sein. Ein Beispiel:

<samlp:Response ...>
  <saml:Assertion ...>
    <saml:Subject>
      <saml:NameID ...>...</saml:NameID>
      <saml:SubjectConfirmation ...>
        <saml:SubjectConfirmationData Recipient="https://ghe.corp.example.com/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-Authentifizierung

GitHub Enterprise Server logs error messages for failed SAML authentication in the authentication log at /var/log/github/auth.log. For more information about SAML response requirements, see "Response message requirements."

Error: "Another user already owns the account"

When a user signs in to GitHub Enterprise Server for the first time with SAML authentication, GitHub Enterprise Server creates a user account on the instance and maps the SAML NameID to the account.

When the user signs in again, GitHub Enterprise Server compares the account's NameID mapping to the IdP's response. If the NameID in the IdP's response no longer matches the NameID that GitHub Enterprise Server expects for the user, the sign-in will fail. The user will see the following message.

Another user already owns the account. Please have your administrator check the authentication log.

The message typically indicates that the person's username or email address has changed on the IdP. For help updating the NameID mapping, contact GitHub Enterprise-Support oder GitHub Premium-Support.

Wenn die SAML-Antwort nicht signiert ist oder die Signatur nicht mit dem Inhalt übereinstimmt, wird im Authentifizierungsprotokoll die folgende Fehlermeldung angezeigt:

Wenn der Empfänger nicht mit der Assertionsverbraucherdienst-URL übereinstimmt, wird im Authentifizierungsprotokoll die folgende Fehlermeldung angezeigt:

Recipient in the SAML response must not be blank.

Recipient in the SAML response was not valid.

Ensure that you set the value for Recipient on your IdP to the full ACS URL for your GitHub Enterprise Server instance. For example, https://ghe.corp.example.com/saml/consume.

Error: "SAML Response is not signed or has been modified"

If your IdP does not sign the SAML response, or the signature does not match the contents, the following error message will appear in the authentication log.

SAML Response is not signed or has been modified.

Ensure that you configure signed assertions for the GitHub Enterprise Server application on your IdP.

Error: "Audience is invalid" or "No assertion found"

If the IdP's response has a missing or incorrect value for Audience, the following error message will appear in the authentication log.

Audience is invalid. Audience attribute does not match https://YOUR-INSTANCE-URL

Ensure that you set the value for Audience on your IdP to the EntityId for your GitHub Enterprise Server instance, which is the full URL to your GitHub Enterprise Server instance. For example, https://ghe.corp.example.com.