Rest-API-Import für Profile und Gruppen mit SCIM

Just Social bietet eine Rest-API an, um Nutzer und Gruppen anzulegen, zu verändern oder zu löschen. Die Implementierung orientiert sich an der SCIM 2 Spezifikation. https://scim.cloud/ bietet einen Überblick über SCIM sowie Links zu den entsprechenden RFCs.

Einrichtung in Just Social

In der Admin-App unter "Anbindungen -> SCIM Profile/Gruppen Import" SCIM aktivieren:

Es wird automatisch ein API-Token erzeugt. Dieses muss als Bearer Token bei jedem Request mitgeschickt werden.

Die Verbindungs-URL ist der Basispfad für spätere Anfragen an die API.

Unter "Attributszuordnung" kann das Mapping von importierten Werten zu Just-Profilfeldern konfiguriert werden. Dieses kann jederzeit angepasst werden, ohne dass Profile hinterher erneut importiert werden müssen. Just Social speichert die über die API übertragenen Daten im Rohformat. Beim Ändern des Attributs-Mappings wird das neue Mapping auf die bereits vorhandenen Rohdaten angewandt.

Einige Zuordnungen können nicht manuell festgelegt werden:

• Das Feld "username" wird immer dem Login-Namen zugeordnet. Soll der Nutzer Systembenachrichtigungen via E-Mail erhalten können, muss hier die E-Mail-Adresse des Nutzers übergeben werden, an die die System-Mails verschickt werden sollen. Das ist wichtig z.B. zum Zurücksetzen des Passworts.

Sofern ihr Profilfelder verwendet, die nicht von SCIM vorgegeben wurden, können diese wie folgt übergeben werden (bitte denkt daran, dass diese Felder auch in der Admin App bei der Attributszuordnung in Just Social entsprechend erst angelegt werden müssen, siehe auch "Eigene Attributszuordnung"):

  "urn:ietf:params:scim:schemas:extension:justsocial:1.0:User": {
    "CustomAttribute1": "foobar",
    "CustomAttribute2": "barbaz"
  }

Eine Schritt für Schritt Anleitung für die Attributszuordung findet ihr unter: "Attributszordnung".

Dieser Import kann grundsätzlich auch mit einem bestehenden System und existierenden Nutzern/Gruppen verwendet werden. Stimmt der importierte "username" mit dem Login-Namen eines bestehenden Nutzers überein, so wird kein neuer Nutzer angelegt, sondern der bestehende mit dem importierten Nutzer verknüpft und mit den importierten Daten aktualisiert. Für Gruppen existiert ein solcher Mechanismus NICHT.

Profile CRUD

Bei allen Requests muss das weiter oben generierte API-Token im Authorization-Header mitgeschickt werden.

Sämtliche Endpunkte entsprechen dem SCIM-Standard (siehe RFC 7644) und werden hier nicht vollumfänglich beschrieben. Stattdessen folgen einige Beispiele. 

Profil anlegen

RFC 7644 Sektion 3.3

Beim Anlegen eines Profils müssen mindestens die folgenden Pflichtfelder übergeben werden:

• userName -> wird immer dem Login-Namen zugeordnet
• externalId -> Id, über die Just-Profil und importiertes Profil verknüpft werden
• name.familyName -> Nachname
• name.givenName -> Vorname

POST <Verbindungs-URL>/Users  HTTP/1.1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"bjensen",
  "externalId":"15b0afb6-a020-4fad-9e05-6455fb170de4",
  "name":{
    "familyName":"Jensen",
    "givenName":"Barbara"
  }
}

Ist das Anlegen des Profils erfolgreich, liefert der Server den Statuscode 201 (Created) sowie das angelegte Profil zurück:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "ed564504-1538-4f6c-814b-8d24ffbeaff1",
  "externalId": "15b0afb6-a020-4fad-9e05-6455fb170de4",
  "meta": {
    "resourceType": "UserResource",
    "location": "<Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1"
  },
  "userName": "bjensen",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  }
}

⚠️Damit Profile in Just Social aktiviert sind bzw. bleiben, muss "active": true mitgegeben werden. Ansonsten werden die Profile in Just Social deaktiviert.

Abfrage einzelner Profile mittels ID

RFC 7644 Sektion 3.4.1

Die Abfrage von Profilen liefert nur die Profile, die der Import 'kennt', d.h. nur solche, die bereits einmal importiert wurden. Wird der Profil-Import über SCIM an ein bestehendes Just-System mit existierenden Nutzern angebunden, so werden diese Nutzer NICHT über die SCIM-Requests zurückgegeben, bis auch sie erstmalig importiert wurden.

Über den Endpunkt

GET /Users/<ID>

kann ein einzelner User anhand seiner ID angefragt werden:

GET <Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1
Accept: application/scim+json
Authorization: Bearer <API-Token>

Falls das angefragte Profil existiert, antwortet der Server mit Statuscode 200 (Ok) und dem Profil:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "ed564504-1538-4f6c-814b-8d24ffbeaff1",
  "externalId": "15b0afb6-a020-4fad-9e05-6455fb170de4",
  "meta": {
    "resourceType": "UserResource",
    "location": "<Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1"
  },
  "userName": "bjensen",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  }
}

Existiert das Profil nicht, liefert der Server einen Statuscode 404 (Not found).

Filtern von Profilen mittels Username

RFC 7644 Sektion 3.4.2.2

Den vollen Umfang der in der SCIM-Spezifikation definierten Filter- und Query-Parameter unterstützt Just Social derzeit noch nicht. Es können jedoch mittels Filter-Ausdruck Profile anhand ihres Username gesucht werden:

GET <Verbindungs-URL>/Users?filter=username eq "bjensen"
Accept: application/scim+json
Authorization: Bearer <API-Token>

Hier antwortet der Server immer mit einem Statuscode 200 (Ok) und entweder mit einer leeren Liste, falls kein Profil gefunden wurde, oder einer Liste der Ergebnisse:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "ed564504-1538-4f6c-814b-8d24ffbeaff1",
      "externalId": "15b0afb6-a020-4fad-9e05-6455fb170de4",
      "meta": {
        "resourceType": "UserResource",
        "location": "<Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1"
      },
      "userName": "bjensen",
      "name": {
        "familyName": "Jensen",
        "givenName": "Barbara"
      }
    }
  ]
}

Abfrage aller Profile

RFC 7644 Sektion 3.4.2

Die Abfrage aller Profile über den in der SCIM-Spezifikation definierten Endpunkt /Users geht wie folgt:

GET <Verbindungs-URL>/Users
Accept: application/scim+json
Authorization: Bearer <API-Token>

Beschränkung der zurückgegebenen Attribute

RFC 7644 Sektion 3.4.2.5

Allen GET-Requests können Query-Parameter mitgegeben werden, über die gesteuert werden kann, welche Attribute der Profile zurückgegeben werden sollen.

Mit dem Parameter "excludedAttributes" können bestimmte Attribute ausgeschlossen werden.

Mit dem Parameter "attributes" kann die Rückgabe auf die angegebenen Attribute eingeschränkt werden.

Um z.B. nur Vorname und Username ausgeben zu lassen:

GET <Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1?attributes=name.givenName&attributes=userName
Accept: application/scim+json
Authorization: Bearer <API-Token>

Ergebnis:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "ed564504-1538-4f6c-814b-8d24ffbeaff1",
  "userName": "bjensen",
  "name": {
    "givenName": "Barbara"
  }
}

Um z.B. alle Attribute außer dem Nachnamen ausgeben zu lassen:

GET <Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1?excludedAttributes=name.familyName
Accept: application/scim+json
Authorization: Bearer <API-Token>

Ergebnis:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "ed564504-1538-4f6c-814b-8d24ffbeaff1",
  "externalId": "15b0afb6-a020-4fad-9e05-6455fb170de4",
  "meta": {
    "resourceType": "UserResource",
    "location": "https://mcpete.just-ag.com/just-import/api/scim/v2/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1"
  },
  "userName": "bjensen",
  "name": {
    "givenName": "Barbara"
  }
}

Aktualisieren eines kompletten Profils

RFC 7644 Sektion 3.5.1

Mittels PUT-Requests können komplette Profile aktualisiert werden. Dabei müssen alle oben genannten Pflichtfelder ebenfalls übermittelt werden.

PUT <Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"bjensen",
  "externalId":"15b0afb6-a020-4fad-9e05-6455fb170de4",
  "name":{
    "familyName":"Jensen",
    "givenName":"Barbara"
  },
  "roles":[],
  "emails":[
    {
        "value":"bjensen@example.com",
        "type":"work"
    }
  ]
}

Der Server antwortet im Erfolgsfall mit einem Statuscode 200 (Ok) und dem vollständigen Profil:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "id": "ed564504-1538-4f6c-814b-8d24ffbeaff1",
  "externalId": "15b0afb6-a020-4fad-9e05-6455fb170de4",
  "meta": {
    "resourceType": "UserResource",
    "location": "<Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1"
  },
  "userName": "bjensen",
  "name": {
    "familyName": "Jensen",
    "givenName": "Barbara"
  },
  "emails": [
    {
      "value": "bjensen@example.com",
      "type": "work"
    }
  ]
}

Sollte das Profil noch nicht existieren, antwortet der Server mit einem Statuscode 404 (Not found).

Aktualisieren einzelner Attribute eines Profils

RFC 7644 Sektion 3.5.2

Mittels PATCH-Requests können eines oder mehrere Attribute eines Profils aktualisiert werden.

PATCH <Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "emails[type eq \"private\"].value",
      "value": "babs@example.com"
    }
  ]
}

Bei Erfolg antwortet der Server mit Statuscode 200 (Ok) und dem vollständigen Profil.

Es gibt 3 Arten von Patch-Operations: "add", "remove" und "replace". "add" fügt neue Attribute hinzu, "remove" entfernt sie und mit "replace" können existierende Attribute geändert werden. Um fehlertoleranter gegenüber Microsoft Entra Id zu sein, erlaubt Just Social auch das Hinzufügen neuer Attribute mittels "replace". Es kann also immer "replace" statt "add" genutzt werden. Existiert ein Attribut mit dem angegeben Pfad bereits, wird es ersetzt, andernfalls neu angelegt.

Löschen von Profilen

RFC 7644 Sektion 3.6

Per DELETE-Request können Profile gelöscht werden.

DELETE <Verbindungs-URL>/Users/ed564504-1538-4f6c-814b-8d24ffbeaff1
Authorization: Bearer <API-Token>

Im Erfolgsfall antwortet der Server mit Statuscode 204 (No Content).

Importieren von Passwörtern

Passwörter können über das User-Attribut "password" importiert werden. 
Passwörter können nicht gelöscht werden und dürfen 8-256 Zeichen lang sein. 

{
 "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User"
 ],
 "userName": "bjensen",
 "externalId": "14c0afb6-a220-4fad-9e05-6455fb170de4",
 "name": {
   "familyName": "Jensen",
   "givenName": "Barbara"
 },
 "password": "supersicher123!",
 "active": "true"
}

People-Gruppen CRUD

Das importieren von Gruppen funktioniert über den Endpunkt /Groups analog zu den Profilen, nur dass hier keine Attributszuordnung möglich ist.

People-Gruppe anlegen

RFC 7644 Sektion 3.3

Beim Anlegen einer Gruppe muss das Attribut "displayName" übergeben werden - das ist der Name der Gruppe. Das Übergeben von Mitgliedern ist optional.

POST <Verbindungs-URL>/Groups
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName":"HR",
  "members": [
    {
      "value":"ed564504-1538-4f6c-814b-8d24ffbeaff1"
    }
  ]
}

Das Attribut "value" bei den Mitgliedern ist die ID des Profils.

Ist das Anlegen der Gruppe erfolgreich, liefert der Server den Statuscode 201 (Created) sowie die angelegte Gruppe:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "09d39696-82b8-4fd6-beef-32425e526ee1",
  "meta": {
    "resourceType": "GroupResource",
    "location": "<Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1"
  },
  "displayName": "HR",
  "members": [
    {
      "value": "ed564504-1538-4f6c-814b-8d24ffbeaff1"
    }
  ]
}

Es ist derzeit nicht möglich, importierte Gruppen mit bereits in Just Social bestehenden zu verknüpfen. Wird eine Gruppe mit gleichem Namen wie eine bereits bestehende importiert, so gibt es hinterher 2 Gruppen diesen Namens.

Abfragen einzelner People-Gruppen mittels ID

RFC 7644 Sektion 3.4.1

Analog zu den Profilen liefert die Abfrage von Gruppen nur die Gruppen, die der Import "kennt", d.h. nur solche, die bereits einmal importiert wurden. Wird der Gruppen-Import über SCIM an ein bestehendes Just-System mit existierenden Gruppen angebunden, so werden diese Gruppen NICHT über die SCIM-Requests zurückgegeben.

Über den Endpunkt

GET /Groups/<ID>

kann eine einzelne Gruppe anhand ihrer ID angefragt werden:

GET <Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1
Accept: application/scim+json
Authorization: Bearer <API-Token>

Falls die angefragte Gruppe existiert, antwortet der Server mit Statuscode 200 (Ok) und der Gruppe:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "09d39696-82b8-4fd6-beef-32425e526ee1",
  "meta": {
    "resourceType": "GroupResource",
    "location": "<Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1"
  },
  "displayName": "HR",
  "members": [
    {
      "value": "ed564504-1538-4f6c-814b-8d24ffbeaff1"
    }
  ]
}

Existiert die Gruppe nicht, liefert der Server einen Statuscode 404 (Not found).

Filtern von People-Gruppen mittels DisplayName

RFC 7644 Sektion 3.4.2.2

Den vollen Umfang der in der SCIM-Spezifikation definierten Filter- und Query-Parameter unterstützt Just Social derzeit noch nicht. Es können jedoch mittels Filter-Ausdruck Gruppen anhand ihres DisplayName gesucht werden:

GET <Verbindungs-URL>/Groups?filter=displayName eq "HR"
Accept: application/scim+json
Authorization: Bearer <API-Token>

Hier antwortet der Server immer mit einem Statuscode 200 (Ok) und entweder mit einer leeren Liste, falls keine Gruppe gefunden wurde oder einer Liste der Ergebnisse:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:Group"
      ],
      "id": "09d39696-82b8-4fd6-beef-32425e526ee1",
      "meta": {
        "resourceType": "GroupResource",
        "location": "<Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1"
      },
      "displayName": "HR",
      "members": [
        {
          "value": "ed564504-1538-4f6c-814b-8d24ffbeaff1"
        }
      ]
    }
  ]
}

Abfrage aller People-Gruppen

RFC 7644 Sektion 3.4.2

Die Abfrage aller Gruppen über den in der SCIM-Spezifikation definierten Endpunkt /Groups unterstützt Just Social derzeit noch nicht.

GET <Verbindungs-URL>/Groups
Accept: application/scim+json
Authorization: Bearer <API-Token>

Aktuell wird hier immer eine leere Liste geliefert:

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 0,
  "Resources": []
}

Austauschen einer People-Gruppe

RFC 7644 Sektion 3.5.1

Mittels PUT-Request kann eine komplette Gruppe überschrieben werden. Dadurch werden z.B. alle bisherigen Mitglieder, die nicht erneut mitgeschickt werden, entfernt.

PUT <Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "displayName":"HR",
  "members": [
    {
      "value": "a77dc9e6-33d0-4fb3-9bb8-5765e527a2dc"
    }
  ]
}

Bei Erfolg liefert der Server den Statuscode 200 (Ok) und die aktualisierte Gruppe:

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "id": "09d39696-82b8-4fd6-beef-32425e526ee1",
  "meta": {
    "resourceType": "GroupResource",
    "location": "<Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1"
  },
  "displayName": "HR",
  "members": [
    {
      "value": "a77dc9e6-33d0-4fb3-9bb8-5765e527a2dc"
    }
  ]
}

Hinzufügen / Entfernen von Mitgliedern

RFC 7644 Sektion 3.5.2

Mittels PATCH-Request können Mitglieder hinzugefügt und entfernt, sowie der Name der Gruppe geändert werden. Hierfür werden wie bei den Profilen PatchOperations genutzt.

Hinzufügen von Mitgliedern:

PATCH <Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [
        {
          "value": "a77dc9e6-33d0-4fb3-9bb8-5765e527a2dc"
        }
      ]
    }
  ]
}

Entfernen von Mitgliedern:

PATCH <Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "remove",
      "path": "members[value eq \"a77dc9e6-33d0-4fb3-9bb8-5765e527a2dc\"]"
    }
  ]
}

Austauschen aller Mitglieder:

(alle bisherigen Mitglieder, die nicht übermittelt werden, werden entfernt)

PATCH <Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1
Accept: application/scim+json
Content-Type: application/scim+json
Authorization: Bearer <API-Token>
{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "members",
      "value": [
        {
          "value": "42017fc3-bdc3-48dc-be3f-1ad808a1a763"
        },
        {
          "value": "1488cd78-0505-4cb1-b814-cf79ef6616c5"
        }
      ]
    }
  ]
}

Ergebnis ist im Erfolgsfall Statuscode 200 (Ok) und die aktualisierte Gruppe.

Löschen von People-Gruppen

RFC 7644 Sektion 3.6

Gruppen können mittels DELETE-Request gelöscht werden.

DELETE <Verbindungs-URL>/Groups/09d39696-82b8-4fd6-beef-32425e526ee1
Authorization: Bearer <API-Token>

Im Erfolgsfall antwortet der Server mit 204 (No Content).