Skip to main content

Bereitstellen von Benutzern mit SCIM mithilfe der REST-API

Sie können den Lebenszyklus der Benutzerkonten Ihres Unternehmens auf GitHub.com von Ihrem Identitätsanbieter (IdP) mit REST-API von GitHub für System for Cross-Domain Identity Management (SCIM) verwalten.

Wer kann dieses Feature verwenden?

Um Benutzer*innen im Unternehmen mit deinem Identitätsanbieter zu verwalten, muss dein Unternehmen für Enterprise Managed Users aktiviert sein. Dies ist in GitHub Enterprise Cloud verfügbar. Weitere Informationen findest du unter Informationen zu Enterprise Managed Users.

Hinweise:

  • Die Unterstützung der Bereitstellung des öffentlichen SCIM-Schemas von GitHub für Benutzer befindet sich in der privaten Betaversion und kann noch geändert werden. Um Zugang zur Beta-Version zu erhalten, wenden Sie sich bitte an Ihren Kundenbetreuer unter Vertriebsteam von GitHub.
  • Mit diesem Vorgang kannst du den Zugriff auf dein Unternehmen über GitHub Enterprise Cloud mithilfe von SCIM bereitstellen. Der Vorgang ist nur für die Verwendung mit Enterprise Managed Users verfügbar. Wenn du Enterprise Managed Users nicht verwendest und den Zugriff auf deine Organisationen mit SCIM bereitstellen möchtest, siehe „REST-API-Endpunkte für SCIM“.
  • GitHub empfiehlt, die Bereitstellung in einer Umgebung zu testen, die von den Produktionsdaten auf Ihrem IdP und GitHub.com isoliert ist.

Informationen zur Bereitstellung für Enterprise Managed Users

Zum Erstellen, Verwalten und Deaktivieren von Benutzerkonten für Ihre Unternehmensmitglieder mit GitHub.com muss Ihr IdP SCIM für die Kommunikation mit GitHub implementieren. SCIM ist eine offene Spezifikation für die Verwaltung von Benutzeridentitäten zwischen Systemen. Verschiedene IdPs bieten unterschiedliche Erfahrungen für die Konfiguration der SCIM-Bereitstellung. Weitere Informationen zur Bereitstellung von GitHub Enterprise Cloud finden Sie unter „Konfigurieren der SCIM-Bereitstellung für Enterprise Managed Users“.

GitHub arbeitet in Partnerschaft mit einigen Entwicklern von Identitätsverwaltungssystemen an einer Integration in Enterprise Managed Users auf einem vorbereiteten Weg. Wenn Ihr Unternehmen kein Partner-IDP verwendet, können Sie die Bereitstellung über ein Identitätssystem konfigurieren, das mit der REST API von GitHub kommuniziert. Dieses Handbuch hilft Ihnen, die folgenden Themen im Zusammenhang mit der Implementierung von GitHub zu verstehen.

  • So überprüfen und streamen Sie detaillierte Überwachungsprotokolle für Ihr Unternehmen
  • Die REST-API, einschließlich Endpunkte für SCIM und Nutzungserwartungen
  • Problembehandlung

Alternativ können Sie einen Partner-IDP sowohl für die Authentifizierung als auch für die Bereitstellung verwenden. Weitere Informationen findest du unter Informationen zu Enterprise Managed Users.

GitHub hat nicht jeden IdP getestet. GitHub-Support bietet eingeschränkte Unterstützung für Partner-IdP. Möglicherweise können Sie einen IdP integrieren, der der SCIM-Spezifikation und den Richtlinien von GitHub entspricht, aber Unterstützung des IdP selbst oder zum Erstellen einer Integration finden Sie in der Dokumentation, dem Supportteam oder anderen Ressourcen des Entwicklers.

Voraussetzungen

  • Bevor Sie die Bereitstellung konfigurieren, müssen Sie die Authentifizierung konfigurieren. Weitere Informationen finden Sie unter „Konfigurieren der Authentifizierung für durch Enterprise verwaltete Benutzer“.

  • Stellen Sie vor der Konfiguration der Bereitstellung sicher, dass Sie die Integrationsanforderungen und die Unterstützungsebene für Ihren IdP verstehen. Weitere Informationen finden Sie unter „Informationen zu Enterprise Managed Users“.

  • Um die Integration mit der REST-API von GitHub zu erreichen, muss der IdP den Standard für System for Cross-Domain Identity Management (SCIM) 2.0 unterstützen. Weitere Informationen finden Sie hier auf den folgenden RFC auf der IETF-Website.

  • GitHub empfiehlt, Anforderungen mit der zu REST-API-Endpunkten für SCIM authentifizieren indem Sie ein personal access token (classic) nutzen, der mit einem Setupbenutzer Ihres Unternehmens verbunden ist. Das Token erfordert den Geltungsbereich admin:enterprise. Weitere Informationen findest du unter Konfigurieren der SCIM-Bereitstellung für Enterprise Managed Users.

  • Der Benutzer zeichnet für die Systeme auf, die Sie für die Authentifizierung und Bereitstellung verwenden, muss einen eindeutigen Bezeichner freigeben und die Kriterien von GitHub erfüllen. Weitere Informationen finden Sie in der REST-API-Dokumentation unter SCIM.

  • Nachdem Sie die anfängliche Authentifizierung und Bereitstellung konfiguriert haben, empfiehlt GitHub keine Migration zu einer anderen Plattform für die Authentifizierung oder Bereitstellung. Wenn Sie ein vorhandenes Unternehmen zu einer anderen Plattform für die Authentifizierung oder Bereitstellung migrieren müssen, wenden Sie sich unter Vertriebsteam von GitHub an Ihren Kontomanager.

Konfigurieren des Streamings von Überwachungsprotokollen

Das Überwachungsprotokoll für Ihr Unternehmen zeigt Details zu Aktivitäten in Ihrem Unternehmen an. Sie können das Überwachungsprotokoll verwenden, um Ihre Konfiguration von SCIM zu unterstützen. Weitere Informationen findest du unter Informationen zum Überwachungsprotokoll für dein Unternehmen.

Aufgrund des Volumens der Ereignisse in diesem Protokoll behält GitHub die Daten 180 Tage lang bei. Um sicherzustellen, dass Überwachungsprotokolldaten nicht verloren gehen und im Überwachungsprotokoll genauere Aktivitäten angezeigt werden sollen, empfiehlt GitHub, das Streaming von Überwachungsprotokollen zu konfigurieren. Wenn Sie das Überwachungsprotokoll streamen, können Sie optional Ereignisse für API-Anforderungen streamen, einschließlich Anforderungen an Endpunkte für die SCIM-Bereitstellung. Weitere Informationen findest du unter Streamen des Überwachungsprotokolls für ein Unternehmen.

Grundlegendes zur REST-API für SCIM

Um SCIM-Aufrufe zu tätigen und Benutzer zu verwalten, verwenden Sie die REST-API von GitHub. Weitere Informationen über den Zugriff auf Ressourcen in der REST-API finden Sie unter „Erste Schritte mit der REST-API“.

REST-API-Endpunkte für SCIM

In den folgenden Tabellen werden die SCIM-Endpunkte beschrieben, die von der REST-API angeboten werden. Weitere Informationen finden Sie in der REST-API-Dokumentation. Die Dokumentation enthält Codebeispiele, erforderliche Header und Pfadparameter sowie HTTP-Antwortcodes.

Weitere Informationen zur Authentifizierung von Anforderungen an diese Endpunkte finden Sie in der REST-API-Dokumentation unter „SCIM“.

Anforderungen, die nicht den Erwartungen der REST-API entsprechen, geben einen 400 Bad Request-Fehler zurück.

REST-API-Endpunkte für die Benutzerverwaltung

Um Benutzer bereitzustellen, stellen Sie Anforderungen an die folgenden REST-API-Endpunkte.

AktionMethodeEndpunkt und weitere Informationen
Erstellen eines BenutzersPOSTBereitstellen eines SCIM-Unternehmensbenutzers
Einen Benutzer abrufenGETAbrufen von SCIM-Bereitstellungsinformationen für einen Unternehmensbenutzer
Aktualisieren aller Attribute eines BenutzersPUTFestlegen von SCIM-Informationen für einen bereitgestellten Unternehmensbenutzer
Aktualisieren eines einzelnen BenutzerattributesPATCHAktualisieren eines Attributs für einen SCIM-Unternehmensbenutzer
Alle Benutzer auflistenGETAuflisten von gemäß SCIM bereitgestellten Identitäten für ein Unternehmen
Löschen eines BenutzersDELETELöschen eines SCIM-Benutzers aus einem Unternehmen

REST-API-Endpunkte für die Gruppenverwaltung

Um den Zugriff auf Repositorys in Ihrem Unternehmen zu steuern, kann Ihre SCIM-Integration Organisations- und Teammitgliedschaften für Benutzer über Gruppen auf Ihrem IdP verwalten. Weitere Informationen findest du unter Verwalten von Teammitgliedschaften mit Identitätsanbietergruppen.

Um Gruppen zu verwalten, stellen Sie Anforderungen an die folgenden REST-API-Endpunkte.

AktionMethodeEndpunkt und weitere Informationen
Erstellen einer GruppePOSTBereitstellen einer SCIM-Unternehmensgruppe
Abrufen einer GruppeGETAbrufen von SCIM-Bereitstellungsinformationen für eine Unternehmensgruppe
Aktualisieren aller Attribute einer GruppePUTFestlegen von SCIM-Informationen für eine bereitgestellte Unternehmensgruppe
Aktualisieren eines einzelnen GruppenattributesPATCHAktualisieren eines Attributs für eine SCIM-Unternehmensgruppe
Alle Gruppen auflistenGETAuflisten von bereitgestellten SCIM-Gruppen für ein Unternehmen
Löschen einer GruppeDELETELöschen einer SCIM-Gruppe aus einem Unternehmen

Informationen zu Quotengrenzen

Hinweis: Weisen Sie der SCIM-Integration auf Ihrem IdP maximal 1.000 Benutzer pro Stunde zu, um eine Überschreitung der Ratenbegrenzung für GitHub Enterprise Cloud zu vermeiden. Wenn du Gruppen verwendest, um der Identitätsanbieteranwendung Benutzerinnen hinzuzufügen, füge den einzelnen Gruppen jeweils maximal 1,000 Benutzerinnen pro Stunde hinzu. Bei Überschreitung dieser Schwellenwerte tritt bei der Benutzerbereitstellung möglicherweise ein Ratenlimitfehler auf, und die Bereitstellung ist nicht erfolgreich. Du kannst deine IdP-Protokolle überprüfen, um zu bestätigen, ob versuchte SCIM-Bereitstellungen oder Pushvorgänge aufgrund eines Fehlers bei der Ratenbegrenzung fehlgeschlagen sind. Die Antwort auf einen fehlgeschlagenen Bereitstellungsversuch hängt vom IdP ab.

Weitere Informationen findest du unter Ratenbegrenzungen für die REST-API.

Benutzer- und Gruppenattribute

Anforderungen an die REST-API unterstützen bestimmte Attribute für Benutzer und Gruppen. Weitere Informationen finden Sie unter „Unterstützte SCIM-Benutzerattribute“ und „Unterstützte SCIM-Gruppenattribute“ in der REST-API-Dokumentation für SCIM-Vorgänge.

Sie können z. B. das roles-Attribut verwenden, um einem Benutzer oder einer Gruppe eine Rolle im Unternehmen zuzuweisen. Wenn Sie einem Benutzer mehrere Rollen gewähren, hat die Rolle mit einem privilegierteren Zugriff Vorrang.

RoleWeitere Informationen findest du unter „Rollen in einem Unternehmen“
enterprise_ownerUnternehmensbesitzer
billing_managerAbrechnungsmanager
userEnterprise-Mitglieder
guest_collaboratorGast-Mitarbeiter

Informationen zur Zuordnung External Identities

Nach erfolgreicher Authentifizierung verknüpft GitHub Enterprise Cloud den Benutzer, der sich mit einer von SCIM bereitgestellten Identität authentifiziert hat. Die eindeutigen Bezeichner für Authentifizierung und Bereitstellung müssen übereinstimmen. Weitere Informationen findest du in der REST-API-Dokumentation unter „SCIM“.

Sie können diese Zuordnung für GitHub.com anzeigen. Weitere Informationen findest du unter Anzeigen und Verwalten des SAML-Zugriffs von Benutzer*innen auf dein Unternehmen.

Sicherstellen, dass Benutzer über den gewünschten Zugriff verfügen

Wenn Ihre Integration den Zugriff mithilfe von Gruppen auf Ihrem IdP verwaltet, können Sie überprüfen, ob Benutzer den gewünschten Zugriff erhalten. Sie können die REST-API verwenden, um die Gruppenmitgliedschaften Ihres IdP mit dem Verständnis von GitHub dieser Gruppen. Weitere Informationen findest du in der Dokumentation zur REST-API unter REST-API-Endpunkte für externe Gruppen und Teams.

Informationen zum Anhalten und erneuten Bereitstellen von Benutzern

Sie können keine verwaltetes Benutzerkonto für GitHub.com vollständig löschen. Stattdessen können Sie das Konto vorübergehend oder dauerhaft sperren.

Um einen Benutzer vorübergehend anzusetzen, legt das Attribut des active Benutzerdatensatzes auf false die Verwendung einer PATCH oder PUT Anforderung fest. Nachdem Sie ein Konto vorübergehend ausgesetzt haben, kann sich der Benutzer nicht mehr in Ihrem Unternehmen anmelden, um auf GitHub.com zuzugreifen. Weitere Informationen finden Sie unter „Aktualisieren eines Attributs für einen SCIM Unternehmensbenutzer“ oder „Festlegen von SCIM-Informationen für einen bereitgestellten Unternehmensbenutzer“ in der REST-API-Dokumentation für SCIM-Vorgänge.

Um einen Benutzer dauerhaft auszusetzen, senden Sie eine DELETE-Anforderung. Wenn Sie ein Konto dauerhaft sperren, können Sie das Konto nicht erneut aktivieren. Weitere Informationen finden Sie unter „Löschen eines SCIM-Benutzers aus einem Unternehmen“ in der REST-API-Dokumentation für SCIM-Vorgänge.

Wenn Sie einen Benutzer erneut bereitstellen möchten, legen Sie das Attribut des active-Benutzerdatensatzes auf true die Verwendung eines POST, PUToder PATCH einer Anforderung fest. Wenn Sie das Konto dauerhaft ausgesetzt haben, erstellt ein nachfolgendes Bereitstellungsereignis ein neues Konto für die Person, die sich anmeldet. Das neu bereitgestellte Konto hat keine Beziehung zum ursprünglichen Konto. Weitere Informationen finden Sie unter „Bereitstellen eines Attributs für einen SCIM-Unternehmensbenutzer“ oder „Festlegen von SCIM-Informationen für einen bereitgestellten Unternehmensbenutzer“ oder „Aktualisieren eines Attributs für einen SCIM-Unternehmensbenutzer“ in der REST-API-Dokumentation für SCIM-Vorgänge.

Problembehandlung

  • Wenn GitHub Ihre Anforderungen an die REST-API einschränken, finden Sie weitere Informationen unter „Informationen zu Ratenbegrenzungen“.

  • Wenn Sie Überwachungsprotokollstreaming- und Stream-Ereignisse für API-Anforderungen aktivieren, können Sie alle Anforderungen an die REST-API-Endpunkte für SCIM überprüfen, indem Sie nach Ereignissen von den EnterpriseUsersScim- oder EnterpriseGroupsScim-Controllern filtern.

  • Wenn Ihre Integration den Zugriff mithilfe von Gruppen auf Ihrem IdP verwaltet, können Sie external_group-Kategorieereignisse im Überwachungsprotokoll Ihres Unternehmens überprüfen, um den Erfolg von SCIM-Aufrufen zu bestätigen. Sie können auch Informationen zur Problembehandlung auf der Weboberfläche für GitHub anzeigen. Weitere Informationen finden Sie unter Überwachungsprotokollereignisse für Ihre Enterprise und unter Problembehandlung bei der Teammitgliedschaft mit Identitätsanbietergruppen.

Weiterführende Themen