SCIM-Bereitstellung mit der SCIM-API von Udemy konfigurieren

Übersicht

System for Cross-Domain Identity Management (SCIM) ist eine Standard-API, über die du die Bereitstellung/Bereitstellungsaufhebung von Nutzer:innen 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 die Version 2.0 des SCIM-Standards. Die API kann von allen Kunden mit einem Enterprise-Abo genutzt werden.

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

  • Nutzer:innen bereitstellen
  • Bereitstellung von Nutzer:innen aufheben (Deaktivierung)
  • E-Mail-Adressen ändern
  • Nutzerdaten ändern
  • Gruppen bereitstellen
  • Nutzer:innen 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. Dabei handelt es sich um ein Client-Server-Protokoll, wobei der Identitätsanbieter der Client und Udemy Business der Server ist.

Der Vorgang läuft im Prinzip wie folgt ab:

  • Wenn dem:der Nutzer:in im Identitätsanbieter des Kunden Zugriff auf Udemy Business gewährt wird, dann sendet der Identitätsanbieter eine Anforderung an Udemy, um zu überprüfen, ob diese:r Nutzer:in in unserer Datenbank enthalten ist. Damit wird eine Anforderung zur Suche des:der Nutzers:Nutzerin anhand eines Attributs wie „userName“ oder „email“ gestartet.
  • Wenn der:die Nutzer:in nicht vorhanden ist, sendet der Identitätsanbieter eine Anforderung zur Erstellung eines:einer Nutzers:Nutzerin.
  • Wenn der:die Nutzer:in vorhanden ist, sendet der Identitätsanbieter eine Aktualisierungsanforderung für diese:n Nutzer:in.
  • Wenn der Zugriff auf Udemy Business verweigert wird, sendet der Identitätsanbieter eine Anforderung zur Deaktivierung des:der Nutzers:Nutzerin in unserer Datenbank an Udemy.
  • Der Identitätsanbieter kann auch Anforderungen zum Ändern von Nutzerdaten senden.

Wie funktioniert der API-Zugriff?

Um die Autorisierungs-Anmeldedaten 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 Administrator:innen 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://<deinesubdomain>.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.

Aufrufratenlimit

Udemy Business wendet Aufrufratenlimits auf die SCIM-API unter Berücksichtigung des HTTP-Standardprotokolls zu Aufrufratenlimits an. Wenn deine Anfrage das Aufrufratenlimit überschreitet, erscheint der HTTP-Fehlercode 429 und du musst kurz abwarten und es gemäß dem Retry-After--Header erneut versuchen.

SCIM-API-Endpunkte

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 aus, beispielsweise zu den unterstützten Methoden.

GET /Schemas

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

GET /Schemas/Users

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

GET /Schemas/Groups

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

Nutzerendpunkte

Mithilfe dieser Endpunkte kannst du Nutzer:innen auflisten, anhand von Attributen filtern, neue Nutzer:innen hinzufügen, Nutzerdaten aktualisieren oder Nutzer:innen deaktivieren/anonymisieren. 

Falls die SCIM-API nicht alle Nutzer:innen ausgibt, kontaktiere bitte den Support von Udemy Business.

Unterstützte Attribute

 

SCIM-Attribut Erforderlich? Beschreibung  
emails[type="work"]]['value']
 Ja E-Mail-Adresse des:der Nutzers:Nutzerin. Muss eindeutig sein. 
userName
 Ja Der userName vom Identitätsanbieter. Muss eindeutig sein. 
aktiv
 Ja Flag setzen, um Nutzer:innen zu deaktivieren/reaktivieren 
externalId
 Ja Die externalId des:der Nutzers:Nutzerin vom Identitätsanbieter. Muss eindeutig sein. 
urn:ietf:params:scim:schemas:extension:
enterprise:2.0:User:employeeNumber
 Ja Gibt das Feld „employeeNumber“ aus „EnterpriseSchema“ aus und speichert es als Feld „external_id“. 
name.givenName
 Nein Der Vorname des:der Nutzers:Nutzerin. Diese Attribute sind zwar nicht obligatorisch, wir empfehlen die Angabe aber trotzdem, weil es die Identifizierung der Nutzer:innen erleichtert. 
name.familyName
 Nein Der Nachname (Familienname) des:der Nutzers:Nutzerin. Diese Attribute sind zwar nicht obligatorisch, wir empfehlen die Angabe aber trotzdem, weil es die Identifizierung der Nutzer:innen erleichtert. 
name, { givenName, familyName }
 Nein Vor- und Nachname des:der Nutzers:Nutzerin. Diese Attribute sind zwar nicht obligatorisch, wir empfehlen die Angabe aber trotzdem, weil es die Identifizierung der Nutzer:innen erleichtert. 
Titel
 Nein Stellenbezeichnung des:der Nutzers:Nutzerin, z. B. „Senior Engineer“ 
groups
 Nein SCIM-Gruppe(n) des:der Nutzers:Nutzerin


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:innen aus, standardmäßig 12 Nutzer:innen pro Seite. Du kannst

die Anzahl

und

Parameter an startIndex übergeben

um das Abfrageergebnis in Seiten aufgeteilt auszugeben. Zum 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) 
  • Anzahl
    ist die Anzahl von Ressourcen, die in einer Antwortauflistungsseite ausgegeben werden (d. h. das Limit). Du kannst mit einer Anforderung bis zu 1000 Nutzer:innen abrufen. Wenn dieser Wert nicht angegeben ist, wird er standardmäßig auf 12 gesetzt.

Beispielanfrage

GET https://demo.udemy.com/scim/v2/Users 
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 18,
"startIndex": 1,
"Resources": [
{
"id": "KwLzN3",
"externalId": "00u3mlhj4x1E482sK5d7",
"userName": "firstName.lastName@domain.com",
"name": {
"givenName": "firstName",
"familyName": "lastName",
"formatted": "firstName lastName"
},
"emails": [
{
"value": "firstName.lastName@domain.com",
"type": "work",
"primary": true
}
],
"title": "",
"active": true,
"groups": [
{
"value": "NZOaw",
"display": "Group Test",
"$ref": "https://demo.udemy.com/scim/v2/Groups/NZOaw"
},
{
"value": "dn1K8",
"display": "NewGroup2",
"$ref": "https://demo.udemy.com/scim/v2/Groups/dn1K8"
}
],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"meta": {
"resourceType": "User",
"location": "https://demo.udemy.com/scim/v2/Users/KwLzN3",
"created": "2022-01-19T01:11:59Z",
"lastModified": "2024-11-22T21:58:48Z"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "64e63"
}
},
[...]
],
"itemsPerPage": 12
}

 

GET /Users?filter=

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

GET /Users?filter=userName eq "example..name”

Hinweis: Im vorangehenden Beispiel musst du die URL-Parameter kodieren (Prozentkodierung), die URL muss also wie folgt aussehen:

GET /Users?filter=userName%20eq%20%22example.name%22

Dies gibt eine Liste der Nutzerressourcen aus. Wenn keine Treffer vorhanden sind, wird eine leere Liste ausgegeben.

GET Users?filter=groups.value eq "{SCIM_Group_ID}"

Dies gibt alle Nutzer:innen aus, die zu dieser SCIM-Gruppe gehören

Folgende Filter werden unterstützt:

userName
externalID
emails[type eq=”work”]
groups

Folgende Operatoren werden unterstützt:

und
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:innen in Udemy Business verwendet.

Die Antwort enthält ein

Der id-Parameter

Attribut, das in allen nachfolgenden Anforderungen für Verweise auf diese:n Nutzer:in verwendet werden muss.

Beachte bitte Folgendes:

  • Neue Nutzer:innen, 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 diese:n Nutzer:in eine offene Einladung vorhanden war, wird sie zu diesem Zeitpunkt genutzt.
    Der Nutzer bzw. die Nutzerin wird entsprechend den Angaben in der Einladung ggf. zu Gruppen hinzugefügt und/oder der entsprechenden Rolle bzw. entsprechenden Kursen zugewiesen.
  • Wenn versucht wird, eine:n Nutzer:in zu erstellen, der:die in Udemy Business schon vorhanden ist, wird diese:r Nutzer:in dann durch SCIM verwaltet (auf der Seite „Nutzer:innen verwalten“, durch ein kleines Link-Symbol gekennzeichnet). Dies ändert weder den Status noch die Lizenznutzung dieses:deser Nutzers:Nutzerin. Wenn der:die Nutzer:in aktiv war, bleibt er:sie aktiv, und wenn er:sie deaktiviert war, bleibt er:sie deaktiviert.

Beispielanfrage

 

POST https://demo.udemy.com/scim/v2/Users 
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"active": true,
"emails": [
{
"primary": true,
"type": "work",
"value": "demo.user@test.com"
}
],
"externalId" : "externalIdValue",
"meta": {
"resourceType": "User"
},
"userName": "DemoTest",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "externalIdValue"
},
"name": {
"familyName": "Test",
"formatted": "formatted",
"givenName": "Demo"
}
}

Beispielantwort

{
"id": "MPD698",
"name": {
"givenName": "Demo",
"familyName": "Test",
"formatted": "Demo Test"
},
"emails": [
{
"value": "demo.user@test.com",
"type": "work",
"primary": true
}
],
"title": "",
"active": true,
"groups": [],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"meta": {
"resourceType": "User",
"location": "https://demo.udemy.com/scim/v2/Users/MPD698",
"created": "2024-12-27T22:00:25Z",
"lastModified": "2024-12-27T22:00:26Z"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "externalIdValue"
},
"userName": "DemoTest",
"externalId": "externalIdValue"
}

 

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:einer angegebenen Nutzer:in abgerufen werden.

Der id-Parameter

in der vorangehenden Anforderung ist eine eindeutige Kennung, die bei der Erstellung des:der Nutzers:Nutzerin mithilfe von SCIM oder bei einer Auflistung aller vorhandenen Nutzer:innen ausgegeben wurde.

Antwort:

  • HTTP-Statuscode 200 mit der Nutzerressource, wenn erfolgreich
  • HTTP-Statuscode 404, wenn der/die Nutzer:in 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 bzw. der Nutzerin verwendet werden.

Beispielanfrage

PUT https://demo.udemy.com/scim/v2/Users/MPD698
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"id": "MPD698",
"userName": "demo.user@test.com",
"externalId": "NewExternalID",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "NewExternalID"
},
"name": {
"givenName": "demo",
"familyName": "user"
},
"emails": [
{
"value": "demo.user@test.com",
"type": "work",
"primary": true
}
],
"active": true
}

Beispielantwort

{
"id": "MPD698",
"name": {
"givenName": "demo",
"familyName": "user",
"formatted": "demo user"
},
"emails": [
{
"value": "demo.user@test.com",
"type": "work",
"primary": true
}
],
"title": "",
"active": true,
"groups": [],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"meta": {
"resourceType": "User",
"location": "https://demo.udemy.com/scim/v2/Users/MPD698",
"created": "2024-12-27T22:00:25Z",
"lastModified": "2024-12-27T22:17:52Z"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "NewExternalID"
},
"userName": "demo.user@test.com",
"externalId": "NewExternalID"
}

 

Antwort:

  • HTTP-Statuscode 200 und die aktualisierte Nutzerressource
  • HTTP-Statuscode 404, wenn der/die Nutzer:in nicht vorhanden ist
  • HTTP-Statuscode 400, wenn versucht wurde, eine:n Unternehmensbesitzer:in zu deaktivieren
PATCH /Users/<ID>

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

Er kann das Attribut „aktiv“ enthalten, mit dem der:die Nutzer:in deaktiviert oder reaktiviert werden kann.

  • Der Text jeder Anforderung MUSS das Attribut „schemas“ 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 Attribut „path“ kann leer sein. In diesem Fall muss „value“ ein Verzeichnis im Format {"path": "value"} sein.

Beispielanfrage

PATCH https://demo.udemy.com/scim/v2/Users/MPD698 
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [ 
{
"op": "replace",
"path": "userName",
"value": "DemoUserName"
}
]
}

Beispielantwort

{
"id": "MPD698",
"name": {
"givenName": "demo",
"familyName": "user",
"formatted": "demo user"
},
"emails": [
{
"value": "demo.user@test.com",
"type": "work",
"primary": true
}
],
"title": "",
"active": true,
"groups": [
{
"value": "5ypNz",
"display": "NewGroup",
"$ref": "https://demo.udemy.com/scim/v2/Groups/5ypNz"
}
],
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"meta": {
"resourceType": "User",
"location": "https://demo.udemy.com/scim/v2/Users/MPD698",
"created": "2024-12-27T22:00:25Z",
"lastModified": "2024-12-27T22:17:52Z"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "NewExternalID"
},
"userName": "DemoUserName",
"externalId": "NewExternalID"
}

Antwort:

  • HTTP-Statuscode 200 mit der aktualisierten Nutzerressource, wenn erfolgreich
  • HTTP-Statuscode 404, wenn der/die Nutzer:in nicht gefunden wurde
  • HTTP-Statuscode 400, wenn versucht wurde, eine:n Unternehmensbesitzer:in 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 count und itemsPerPage einschließen, um die Ergebnisse in Seiten aufgeteilt auszugeben.

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

Beispielanfrage

GET https://demo.udemy.com/scim/v2/scim/v2/Groups
 "schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 6,
"startIndex": 1,
"Resources": [
{
"id": "NZOaw",
"displayName": "Group Test",
"members": [
{
"value": "KwLzN3",
"display": "firstName lastName",
"type": "User",
"$ref": "https://demo.udemy.com/scim/v2/Users/KwLzN3"
},
{
"value": "eBmzpr",
"display": "user four",
"type": "User",
"$ref": "https://demo.udemy.com/scim/v2/Users/eBmzpr"
}
],
"externalId": null,
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {
"resourceType": "Group",
"location": "https://demo.udemy.com/scim/v2/Groups/NZOaw",
"created": "2024-08-23T22:26:48Z",
"lastModified": "2024-08-23T22:26:48Z"
}
},
[...]
],
"itemsPerPage": 12
}
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 ausgegeben.

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:

und
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
POST /Groups

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

Warnung: Wenn du die Endpunkte POST oder PUT /scim/v2/Groups zum Erstellen von Gruppen nutzt, schließe das Member -Attribut aus deiner Anfrage aus. Alle bestimmten Mitglieder werden ignoriert. Um Nutzer:innen einer Gruppe hinzuzufügen, musst du zuerst die Gruppe erstellen und dann die PATCH /scim/v2/Groups/ separat anrufen

Beispielanfrage 

https://demo.udemy.com/scim/v2/Groups 
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Group1",
"externalId": "234523"
}

Beispielantwort

{
"id": "vREOw",
"displayName": "Group1",
"members": [],
"externalId": "234523",
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {
"resourceType": "Group",
"location": "https://demo.udemy.com/scim/v2/Groups/vREOw",
"created": "2025-01-15T22:24:54Z",
"lastModified": "2025-01-15T22:24:54Z"
}
}
PUT /Groups/<id>

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

Warnung: Wenn du die Endpunkte POST oder PUT /scim/v2/Groups zum Erstellen von Gruppen nutzt, schließe das Member -Attribut aus deiner Anfrage aus. Alle bestimmten Mitglieder werden ignoriert. Um Nutzer:innen einer Gruppe hinzuzufügen, musst du zuerst die Gruppe erstellen und dann die PATCH /scim/v2/Groups/ separat anrufen

Beispielanfrage

PUT https://demo.udemy.com/scim/v2/Groups/vREOw 
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"displayName": "Group1",
"externalId": "MPD699"
}

Beispielantwort

{
"id": "vREOw",
"displayName": "Group1",
"members": [],
"externalId": "MPD699",
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group"
],
"meta": {
"resourceType": "Group",
"location": "https://demo.udemy.com/scim/v2/Groups/vREOw",
"created": "2025-01-08T21:12:53Z",
"lastModified": "2025-01-15T22:35:55Z"
}
}

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

Beispielanfrage

PATCH https://demo.udemy.com/scim/v2/Groups/5ypNz 
{ "schemas": 
["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[
{
"op":"add",
"path": "members",
"value":[{
"display": "demo user",
"$ref":"https://demo.udemy.com/scim/v2/Users/MPD698",
"value": "MPD698"
}
] 
} 
]
}

Beispielantwort

204 kein Inhalt
  • 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 Attribut „schemas“ 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 Attribut „path“ 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 Nutzer:innen zu einer Gruppe sowie die Zuweisungsaufhebung erfolgen asynchron, diese Ä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/einer Nutzer:in zuzuweisen, der/die 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.

Folgende Regeln gelten:

  • Wenn die Gruppe nicht bereitgestellte Mitglieder enthält, werden bereitgestellte Nutzer:innen 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

  • Überblick über SCIM: http://www.simplecloud.info
  • RFC 7642, SCIM - Definitions, Overview, Concepts, and Requirements: https://tools.ietf.org/pdf/rfc7642.pdf (SCIM - Definitionen, Überblick, Konzepte und Anforderungen, in englischer Sprache)
  • RFC 7643, SCIM - Core Schema: https://tools.ietf.org/pdf/rfc7643.pdf (SCIM - Core-Schema, in englischer Sprache)
  • RFC 7644, SCIM - Protocol: https://tools.ietf.org/pdf/rfc7644.pdf (SCIM - Protokoll, in englischer Sprache)

Verwandte Beiträge

Support kontaktieren