SCIM-Bereitstellung mit der SCIM-API von Udemy konfigurieren

Überblick

SCIM (System for Cross-Domain Identity Management) ist eine Standard-API, über die du die Bereitstellung/Bereitstellungsaufhebung von Nutzern und Gruppen sowie die Aktualisierung von Nutzer- und Gruppendaten vom Identitätsanbieter des Kunden in dein Udemy Business-Konto automatisieren kannst.  SCIM wird von verschiedenen Identitätsanbietern wie z. B. Okta, Azure AD und OneLogin unterstützt.  Du kannst die SCIM-API von Udemy Business auch für andere Identitätsanbieter oder selbstentwickelte Tools verwenden.

Wenn in deinem Unternehmen einer der folgenden Identitätsanbieter verwendet wird, dann verwende für die SCIM-Konfiguration bitte die entsprechende Anleitung:

SCIM nutzt eine standardisierte REST-API mit Daten im JSON-Format. Udemy Business unterstützt Version 2.0 des SCIM-Standards. Die API kann von allen Kunden mit Enterprise-Tarif genutzt werden.

Die SCIM-API von Udemy Business unterstützt folgende Funktionen: 

  • Nutzer bereitstellen
  • Bereitstellung von Nutzern aufheben (Deaktivierung)
  • E-Mail-Adressen ändern
  • Nutzerdaten ändern
  • Gruppen bereitstellen
  • Nutzer zu Gruppen hinzufügen bzw. daraus entfernen

Beschreibung des SCIM-Protokolls

Das SCIM-Protokoll ist ein auf Anwendungsebene angewendetes REST-Protokoll für die Bereitstellung und Verwaltung von Identitätsdaten im Web. Es handelt sich um ein Client-Server-Protokoll, wobei der Client der Identitätsanbieter (IdP) und der Server Udemy Business ist.

Der Vorgang läuft im Prinzip wie folgt ab:

  • Wenn dem Nutzer im IdP vom Kunden Zugriff auf Udemy Business gewährt wird, sendet der IdP eine Anforderung an uns, um zu überprüfen, ob dieser Nutzer in unserer Datenbank enthalten ist. Damit wird eine Anforderung zur Suche des Nutzers anhand eines Attributs wie userName oder email gestartet.
  • Wenn der Nutzer nicht vorhanden ist, sendet der IdP eine Anforderung zur Erstellung eines Nutzers.
  • Ist der Nutzer vorhanden, sendet der IdP eine Aktualisierungsanforderung für den Nutzer.
  • Wenn der Zugriff auf Udemy Business verweigert wird, sendet der IdP eine Anforderung zur Deaktivierung des Nutzers in unserer Datenbank an uns.
  • Der IdP kann auch Anforderungen zum Ändern von Nutzerdaten senden.

Wie funktioniert der API-Zugriff?

Um die Autorisierungs-Anmeldeinformationen abzurufen, die du zur Verbindung mit der SCIM-API brauchst, musst du in deinem Udemy Business-Konto über Verwalten -> Einstellungen -> Bereitstellung (SCIM) die SCIM-Integration einrichten. Beachte bitte, dass nur Administratoren auf diese Seite zugreifen können. 

Klicke auf Einrichtung beginnen.
provisioning_scim.png

Wähle nun Anbieter auswählen und dann Benutzerdefiniert.

select_provider.png

Klicke auf Token erzeugen.

generate_token.png

Klicke in diesem Bildschirm auf Kopieren, um den Bearer-Token in die Zwischenablage zu kopieren.

copy_bearer_token.png

 

Du musst den Authorization-HTTP-Header mit dem Bearer-Token in deinen Anforderungen angeben, z. B.:

GET /scim/v2/Users HTTP/1.1

 Host: meinunternehmen.udemy.com

 Accept: application/scim+json

 Authorization: Bearer <hier deinen Bearer-Token eingeben>

Content-Type: application/scim+json

Die SCIM-API von Udemy Business verwendet das HTTP-Protokoll und ist nur über eine sichere HTTPS-Verbindung verfügbar.

Die Basis-URL für die API lautet https://<Unternehmen>.udemy.com/scim/v2/. 

Wenn du eine Anwendung entwickelst, die mit der SCIM-API von Udemy Business interagiert, solltest du dich an den SCIM RFCs orientieren (siehe die Links am Ende dieses Artikels). Die Implementierung der SCIM-API von Udemy Business entspricht dem Standard.

Endpunkte der SCIM-API

Informationsendpunkte

Diese Endpunkte sind zum Abrufen von Informationen vorgesehen und werden zur Konfiguration der Clients verwendet. Sie erfordern keine Authentifizierung, daher brauchst du beim Zugriff auf diese Endpunkte keinen Authorization-Header anzugeben.

GET /ServiceProviderConfig

Gibt Informationen über die SCIM-Implementierung von Udemy Business SCIM zurück, beispielsweise zu den unterstützten Methoden.

GET /Schemas

Gibt Informationen zu den Schemas zurück, die unsere SCIM-Implementierung unterstützt. Unterstützte Schemas sind „Users“ (Nutzer) und „Groups“ (Gruppen).

GET /Schemas/Users

Gibt alle Attribute zurück, die wir für „User“-Ressourcen unterstützen.

GET /Schemas/Groups

Gibt alle Attribute zurück, die wir für „Group“-Ressourcen unterstützen.

Nutzerendpunkte

Mithilfe dieser Endpunkte kannst du Nutzer auflisten, anhand von Attributen filtern, neue Nutzer hinzufügen, Nutzerdaten aktualisieren oder Nutzer deaktivieren/anonymisieren. Beachte aber bitte, dass du dabei nur auf Nutzer zugreifen kannst, die über die SCIM-API erstellt wurden. Innerhalb von Udemy Business erstellte Nutzer sind nur dann verfügbar, wenn du sie über SCIM zusammenführst. Weitere Infos über die Zusammenführung findest du weiter unten.

Unterstützte Attribute

SCIM-Attribut

Erforderlich?

Beschreibung

userName

Ja

Der userName vom Identitätsanbieter. Muss eindeutig sein.

name, { givenName, familyName }

Nein

Vor- und Nachname des Nutzers. Diese Attribute sind zwar nicht erforderlich, wir empfehlen die Angabe aber trotzdem, weil es die Identifizierung der Nutzer erleichtert.

emails[type="work"]]['value']

Ja

Die E-Mail-Adresse des Nutzers, muss eindeutig sein.

active

Ja

Flag setzen, um Nutzer zu deaktivieren/reaktivieren

title

Nein

Stellenbezeichnung des Nutzers, z. B. „Senior Engineer“

externalId

Ja

Die externalId des Nutzers vom Identitätsanbieter. Muss eindeutig sein.

Hinweis: Wenn du andere Attribute angibst, die nicht auf dieser Liste stehen, werden sie ignoriert.

GET /Users

Gibt eine in Seiten aufgeteilte (paginierte) Liste der Nutzer zurück, standardmäßig 12 Nutzer pro Seite. Du kannst die Parameter count und startIndex übergeben, um das Abfrageergebnis in Seiten aufgeteilt auszugeben. Ein Beispiel:

GET /scim/v2/Users?startIndex=1&count=100 HTTP/1.1

 Host: meinunternehmen.udemy.com

 Accept: application/scim+json

 Authorization: Bearer <hier deinen Bearer-Token eingeben>

  • startIndex ist der 1-basierte Index des ersten Ergebnisses im aktuellen Listenergebnissatz (Offset)
  • count ist die Anzahl von Ressourcen, die in einer Antwortauflistungsseite zurückgegeben werden (Limit). Du kannst mit einer Anforderung bis zu 1000 Nutzer abrufen. Wenn dieser Wert nicht angegeben ist, wird er standardmäßig auf 12 gesetzt.

GET /Users?filter=

Dieser Endpunkt wird verwendet, um Nutzer anhand von bestimmten Attributen zu filtern. Du könntest z. B. anhand des Attributs userName suchen:

GET /Users?filter=userName eq "gloria.graynor"

Hinweis: Im vorangehenden Beispiel musst du die URL-Parameter kodieren (Prozentkodierung), die URL muss also wie folgt aussehen:
GET /Users?filter=userName%20eq%20%22gloria.graynor%22

Dies gibt eine Liste der Nutzerressourcen zurück. Wenn keine Treffer vorhanden sind, wird eine leere Liste zurückgegeben.

Folgende Filter werden unterstützt:

  • userName
  • externalID
  • emails[type eq="work"]

Folgende Operatoren werden unterstützt:

  • and
  • eq

Antwort:

  • HTTP-Statuscode 200 mit der Liste der Einheiten, wenn erfolgreich
  • HTTP-Statuscode 501, wenn ein nicht unterstützter Filter angegeben wurde

POST /Users

Dieser Endpunkt wird zum Erstellen (Bereitstellen) neuer Nutzer in Udemy Business verwendet. 

Die Antwort enthält ein id-Attribut, das in allen nachfolgenden Anforderungen für Verweise auf diesen Nutzer verwendet werden muss.

Beachte bitte Folgendes:

  • Neue Nutzer, die mit dieser Methode erstellt werden, belegen keine Lizenz. Sie belegen erst dann eine Lizenz, nachdem sie sich zum ersten Mal angemeldet haben.
  • Wenn für diesen Nutzer eine offene Einladung vorhanden war, wird sie zu diesem Zeitpunkt genutzt.
    Der Nutzer wird entsprechend den Angaben in der Einladung ggf. zu Gruppen hinzugefügt und/oder der entsprechenden Rolle bzw. entsprechenden Kursen zugewiesen.
  • Wenn versucht wird, einen Nutzer zu erstellen, der in Udemy Business schon vorhanden ist, wird dieser Nutzer dann durch SCIM verwaltet (auf der Seite „Nutzer verwalten“ mit einem kleinen Link-Symbol dargestellt). Dies ändert weder den Status noch die Lizenznutzung dieses Nutzers. Wenn der Nutzer aktiv war, bleibt er aktiv, und wenn er deaktiviert war, bleibt er deaktiviert.

Antwort:

  • HTTP-Statuscode 201 und die Nutzerressource, wenn erfolgreich
  • HTTP-Statuscode 409, wenn das Mitglied mit dem gleichen userName im Unternehmen schon vorhanden ist
  • HTTP-Statuscode 400 mit Angaben zum Fehler im Antworttext, wenn die Anforderung die Gültigkeitsprüfung nicht bestanden hat

GET /Users/<ID>

Mithilfe dieses Endpunkts können Nutzerdaten zu einem angegebenen Nutzer abgerufen werden. Der id-Parameter in der vorangehenden Anforderung ist eine eindeutige Kennung, die bei der Erstellung des Nutzers mithilfe von SCIM oder bei einer Auflistung aller vorhandenen Nutzer zurückgegeben wurde.

Antwort:

  • HTTP-Statuscode 200 mit der Nutzerressource, wenn erfolgreich
  • HTTP-Statuscode 404, wenn der Nutzer nicht gefunden wurde

PUT /Users/<ID>

Dieser Endpunkt wird zum Ersetzen (Überschreiben) von Nutzerdaten in Udemy Business verwendet. Wenn das Attribut active angegeben ist, kann es zum Deaktivieren oder Reaktivieren des Nutzers verwendet werden.

Antwort:

  • HTTP-Statuscode 200 und die aktualisierte Nutzerressource
  • HTTP-Statuscode 404, wenn der Nutzer nicht vorhanden ist 
  • HTTP-Statuscode 400, wenn versucht wurde, einen Unternehmensbesitzer zu deaktivieren

PATCH /Users/<ID>

Mithilfe dieses Endpunkts kannst du Teile der Nutzerdaten in unserem System aktualisieren, d. h. nur bestimmte Attribute des Nutzers ändern. Dieser Befehl unterscheidet sich von PUT, womit der gesamte Nutzer ersetzt wird. 

Er kann das Attribut active enthalten, mit dem der Nutzer deaktiviert oder reaktiviert werden kann.

  • Der Text jeder Anforderung MUSS das „schemas“-Attribut mit dem URI-Wert „urn:ietf:params:scim:api:messages:2.0:PatchOp“ enthalten.
  • Der Text einer HTTP PATCH-Anforderung MUSS das Attribut „Operations“ enthalten, dessen Wert ein Array von mindestens einer PATCH-Operation ist.  Jedes PATCH-Operationsobjekt MUSS genau ein „op“-Mitglied haben, dessen Wert die auszuführende Operation angibt und eins von „add“, „remove“ oder „replace“ sein KANN.
  • Das „path“-Attribut kann leer sein. In diesem Fall muss „value“ ein Verzeichnis im Format {"path": "value"} sein.

Antwort:

  • HTTP-Statuscode 200 mit der aktualisierten Nutzerressource, wenn erfolgreich
  • HTTP-Statuscode 404, wenn der Nutzer nicht gefunden wurde
  • HTTP-Statuscode 400, wenn versucht wurde, einen Unternehmensbesitzer zu deaktivieren oder wenn die Operation ungültig ist

Gruppenendpunkte

Unterstützte Attribute

SCIM-Attribut

Erforderlich?

Beschreibung

displayName

Ja

Bezeichnung der Gruppe. Muss innerhalb aller Udemy Business-Gruppen eindeutig sein.

externalId

Nein

Die externalId der Gruppe vom Identitätsanbieter

Hinweis: Wenn du andere Attribute angibst, die nicht auf dieser Liste stehen, werden sie ignoriert.

GET /Groups

Dieser Endpunkt wird verwendet, um eine in Seiten aufgeteilte (paginierte) Liste aller bereitgestellten Gruppen abzurufen. Du kannst die Abfrage-String-Parameter startIndex und count einschließen, um die Ergebnisse in Seiten aufgeteilt auszugeben. 

Beachte bitte, dass nur Gruppen zurückgegeben werden, die mithilfe von SCIM erstellt wurden. Mithilfe von Udemy Business erstellte Gruppen werden nicht zurückgegeben.

GET /Groups?filter=

Dieser Endpunkt wird verwendet, um Gruppen anhand von bestimmten Attributen zu filtern. Du kannst z. B. anhand des Attributs displayName suchen:

GET /Groups?filter=displayName eq "Marketing"

Dies gibt eine Liste der Gruppenressourcen zurück. Wenn keine Treffer vorhanden sind, wird eine leere Liste zurückgegeben.

Beachte bitte, dass du die URL-Parameter kodieren musst (Prozentkodierung), die Anforderung muss also wie folgt aussehen:
GET /Groups?filter=displayName%20eq%20%22Marketing%22

Folgende Filter werden unterstützt:

  • displayName
  • externalId
  • Id
  • member.value\

Folgende Operatoren werden unterstützt:

  • and
  • eq

Antwort:

  • HTTP-Statuscode 200 mit der Liste der Einheiten, wenn erfolgreich
  • HTTP-Statuscode 501, wenn ein nicht unterstützter Filter verwendet wird

POST /Groups

Dieser Endpunkt wird zum Erstellen (Bereitstellen) neuer Gruppen in Udemy Business verwendet. 

Antwort:

  • HTTP-Statuscode 409: Wenn bereits eine bereitgestellte Gruppe mit diesem Namen im Unternehmen vorhanden ist, wird 409 (Konflikt) mit dem scimType-Fehlercode uniqueness („Eindeutigkeit“) zurückgegeben.
  • Wenn die Gruppe erfolgreich erstellt wurde, wird die vollständige Darstellung der Gruppe mit dem HTTP-Statuscode 201 (Erstellt) zusammen mit dem Location-Header, der die URL der erstellten Gruppenressource enthält, zurückgegeben.

GET /Groups/<ID>

Dieser Endpunkt wird zum Abrufen der Gruppendetails von Udemy Business verwendet. 

Antwort:

  • HTTP-Statuscode 200 und eine Gruppenressource
  • HTTP-Statuscode 404, wenn die Gruppe nicht gefunden wurde

PUT /Groups/<ID>

Dieser Endpunkt wird zum Ersetzen der Gruppendetails in Udemy Business verwendet.

Antwort:

  • HTTP-Statuscode 200 und die aktualisierte Gruppenressource 
  • HTTP-Statuscode 404, wenn die Gruppe nicht vorhanden ist 

PATCH /Groups/<ID>

Mithilfe dieses Endpunkts kannst du Teile der Gruppendetails in Udemy Business aktualisieren. 

Der PATCH-Endpunkt ist komplexer als die anderen, da er unterschiedliche Arten von Operationen unterstützt (und zudem Kombinationen der Operationen möglich sind):

  • replace-Operation ändert den angegebenen Wert. In unserem Fall handelt es sich dabei um den Namen oder die Mitglieder der Gruppe.
  • remove-Operation entfernt ein Mitglied aus der Gruppe.
  • add-Operation fügt Mitglieder zur Gruppe hinzu.

Folgende Regeln gelten:

  • Nicht bereitgestellte Mitglieder werden niemals aus der Gruppe entfernt (z. B. bei der „replace“-Operation für Mitglieder).
  • Eine PATCH-Anforderung wird unabhängig von der Anzahl der Operationen als atomar behandelt.

Die Eingaben werden wie folgt validiert:

  • Der Text jeder Anforderung MUSS das „schemas“-Attribut mit dem URI-Wert „urn:ietf:params:scim:api:messages:2.0:PatchOp“ enthalten.
  • Der Text einer HTTP PATCH-Anforderung MUSS das Attribut „Operations“ enthalten, dessen Wert ein Array von mindestens einer PATCH-Operation ist.  Jedes PATCH-Operationsobjekt MUSS genau ein „op“-Mitglied haben, dessen Wert die auszuführende Operation angibt und eins von „add“, „remove“ oder „replace“ sein KANN.
  • Das „path“-Attribut kann leer sein. In diesem Fall muss „value“ ein Verzeichnis im Format {"path": "value"} sein.
  • Für die „Remove“-Operation ist der „members“-Pfad erforderlich.
  • Für die „Add“-Operation muss entweder der „members“- oder der „externalId“-Pfad angegeben werden.
  • Für die „Replace“-Operation kann der „members“-Pfad angegeben werden. Wenn er nicht angegeben ist, werden die Gruppendetails (z. B. der Name der Gruppe), nicht aber die Mitglieder ersetzt.

Hinweis:

  • Die Zuweisung von Nutzern zu einer Gruppe sowie die Zuweisungsaufhebung erfolgen asynchron, Änderungen sind also in Udemy Business nicht sofort sichtbar.
  • Geschachtelte Gruppen werden nicht unterstützt und daher bei dieser Anforderung ignoriert.

Antwort:

  • HTTP-Statuscode 204, wenn die Operation erfolgreich war
  • HTTP-Statuscode 404, wenn die Gruppe nicht vorhanden ist
  • HTTP-Statuscode 404 mit Angaben zum Fehler, wenn versucht wurde, eine Gruppe zu einem Nutzer zuzuweisen, der kein Mitglied dieses Unternehmens ist
  • HTTP-Statuscode 400 mit Angaben zum Fehler im Antworttext, wenn die Anforderung die Gültigkeitsprüfung nicht bestanden hat

DELETE /Groups/<ID>

Dieser Endpunkt wird verwendet, um eine Gruppe aus Udemy Business zu entfernen bzw. ihre Bereitstellung aufzuheben. Beim Löschen einer Gruppe werden die darin enthaltenen Nutzer nicht gelöscht. Sie werden nur aus der gelöschten Gruppe entfernt.

Folgende Regeln gelten:

  • Wenn die Gruppe nicht bereitgestellte Mitglieder enthält, werden bereitgestellte Nutzer aus der Gruppe entfernt und der „OrganizationSCIMGroup“-Eintrag wird gelöscht.

Antwort:

  • HTTP-Statuscode 204, wenn die Operation erfolgreich war
  • HTTP-Statuscode 404, wenn die Gruppe nicht vorhanden ist

Weiterführende Informationen

Verwandte Beiträge

Support kontaktieren