SAML verwenden

SAML ist ein XML-basierter Standard für die Authentifizierung und Autorisierung. GitHub Enterprise Server kann als ein Service Provider (SP) mit Ihrem internen SAML Identity Provider (IdP) funktionieren.

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.

Note: If the NameID for a user does change on the IdP, the user will see an error message when they try to sign in to your GitHub Enterprise Server instance. To restore the user's access, you'll need to update the user account's NameID mapping. For more information, see "Updating a user's SAML NameID."

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:

BenutzernameNormalisierter BenutzernameErgebnis
Ms.Bubblesms-bubblesDieser Benutzername wird erfolgreich erstellt.
!Ms.Bubbles-ms-bubblesDieser Benutzername wird nicht erstellt, da er mit einem Bindestrich beginnt.
Ms.Bubbles!ms-bubbles-Dieser Benutzername wird nicht erstellt, da er mit einem Bindestrich endet.
Ms!!Bubblesms--bubblesDieser Benutzername wird nicht erstellt, da er zwei aufeinanderfolgende Bindestriche enthält.
Ms!Bubblesms-bubblesDieser Benutzername wird nicht erstellt. Obwohl der normalisierte Benutzername gültig ist, ist er bereits vorhanden.
Ms.Bubbles@example.comms-bubblesDieser Benutzername wird nicht erstellt. Obwohl der normalisierte Benutzername gültig ist, ist er bereits vorhanden.

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

Your GitHub Enterprise Server instance's service provider metadata is available at http(s)://[hostname]/saml/metadata.

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.

Standardmäßiger AttributnameTypBeschreibung
NameIDErforderlichEin persistenter Benutzerkennzeichner. Es kann ein beliebiges Format für persistente Namenskennzeichner verwendet werden. Das Element NameID wird für einen GitHub Enterprise Server-Benutzernamen verwendet, sofern keine der alternativen Assertions bereitgestellt wird.
AdministratorOptionalWenn der Wert „true“ lautet, wird der Benutzer automatisch zu einem Administrator hochgestuft. Bei anderen oder nicht vorhandenen Werten wird der Benutzer auf ein normales Benutzerkonto zurückgestuft.
BenutzernameOptionalDer GitHub Enterprise Server-Benutzername.
full_nameOptionalDer Name des Benutzers, der auf seiner Profilseite angezeigt wird. Nach der Bereitstellung können Benutzer ihre Namen ändern.
emailsOptionalDie E-Mail-Adressen für den Benutzer. Es können mehrere angegeben werden.
public_keysOptionalDie öffentlichen SSH-Schlüssel für den Benutzer. Es können mehrere angegeben werden.
gpg_keysOptionalDie GPG-Schlüssel für den Benutzer. Es können mehrere angegeben werden.

SAML-Einstellungen konfigurieren

  1. From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page. Raumschiffsymbol für den Zugriff auf die Einstellungen des Websiteadministrators

  2. Klicke auf der linken Seitenleiste auf Managementkonsole. Registerkarte „Managementkonsole" in der linken Seitenleiste

  3. Klicke auf der linken Seitenleiste auf Authentication (Authentifizierung). Registerkarte „Authentication“ (Authentifizierung) auf der Seitenleiste mit den Einstellungen

  4. Wählen Sie SAML aus. SAML-Authentifizierung

  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. Aktivierung des Kontrollkästchens für integrierte SAML-Authentifizierung

  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. IdP-SSO über SAML

    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. SAML disable admin configuration

  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. SAML-Authentifizierung

  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. SAML-Aussteller

  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. SAML-Methode

  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. SAML-Authentifizierung

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

Zugriff auf Ihre GitHub Enterprise Server-Instanz widerrufen

  1. From an administrative account on GitHub Enterprise Server, click in the upper-right corner of any page. Raumschiffsymbol für den Zugriff auf die Einstellungen des Websiteadministrators
  2. Wählen Sie SAML aus. "All users" sidebar item in site administrator settings
  3. In the list of users, click the username you'd like to update the NameID mapping for. Username in list of instance user accounts
  4. Klicken Sie in der oberen rechte Ecke der Seite auf Security (Sicherheit). Registerkarte „Security“ (Sicherheit)
  5. To the right of "Update SAML NameID", click Edit . SAML-Authentifizierung
  6. In the "NameID" field, type the new NameID for the user. "NameID" field in modal dialog with NameID typed
  7. Click Update NameID. "Update NameID" button under updated NameID value within modal

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. Ensure that the NameID mapping for the user account on GitHub Enterprise Server matches the user's NameID on your IdP. For more information, see "Updating a user's SAML NameID."

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.

Did this doc help you?Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Oder, learn how to contribute.