Unternehmensverzeichnis per SCIM anbinden

Viele Unternehmen führen ihre Beschäftigten und deren Gruppen zentral in einem Identity-Provider, etwa Microsoft Entra ID oder Okta. Statt Personen in knooing von Hand anzulegen, lässt sich dieses Verzeichnis anbinden. Es meldet dann neue Personen, Austritte und Gruppen von selbst an knooing. Der Standard dafür heißt SCIM.

Julia Beispiel bindet in dieser Anleitung das Verzeichnis der Beispiel GmbH an. Sie legt ein SCIM-Token an, gibt es mit der Basis-Adresse an die Person weiter, die den Identity-Provider betreut, und prüft danach, welche Gruppen angekommen sind. Wie aus einer Gruppe eine Rolle in knooing wird, steht im zweiten Teil: Gruppen aus dem Verzeichnis Rollen zuordnen.

Die wichtigsten Begriffe

• Identity-Provider: das System, das die Konten und Gruppen Ihres Unternehmens verwaltet, etwa Microsoft Entra ID oder Okta. Was darin an Personen und Gruppen steht, nennt knooing Ihr Verzeichnis.
• SCIM: ein Standard, mit dem der Identity-Provider Personen und Gruppen an andere Systeme überträgt. knooing unterstützt Benutzer und Gruppen nach SCIM 2.0. Den Teil des Identity-Providers, der überträgt, nennt knooing SCIM-Client.
• SCIM-Token: das Passwort, mit dem sich der Identity-Provider bei knooing ausweist. Es gilt höchstens ein Jahr.
• Basis-Adresse: die Adresse von knooing, an die der Identity-Provider liefert, zum Beispiel https://knooing.beispiel-gmbh.test/api/scim/v2. Sie steht oben im Reiter SCIM-Tokens.
• Rotieren: ein Token durch ein neues ersetzen, bevor es abläuft. Das alte gilt dabei noch eine Schonfrist lang, damit der neue Wert in Ruhe eingetragen werden kann.
• Föderation: die Anmeldung über Ihren Identity-Provider, auch Single Sign-on (SSO) genannt. Der Reiter Föderation zeigt sie nur zur Ansicht; ändern können Sie sie hier nicht.
• Mandant: Ihr Unternehmen in knooing.
• Gruppe: eine Sammlung von Personen im Verzeichnis, etwa alle Beschäftigten im Lager Nord.

In den Bildern markieren Zahlen, wo Sie klicken. (i) markiert, wo Sie etwas ablesen.

Schritt 1: Die Identitätsanbindung öffnen

Klicken Sie unten in der Seitenleiste auf Einstellungen, links auf Nutzer & Rechte und daneben auf Identitätsanbindung. Es öffnet sich der Reiter Föderation. Klicken Sie oben auf den Reiter SCIM-Tokens (1).

1

Im Reiter Föderation steht, ob die Anmeldung über Ihren Identity-Provider schon eingerichtet ist. Der blaue Hinweis zu Revisionen und Freigaben betrifft nur die Föderation. Für die Übertragung per SCIM brauchen Sie die Föderation nicht. Ohne sie können sich die übertragenen Personen aber nicht anmelden.

Warum über das Verzeichnis? Verlässt jemand das Unternehmen, verliert er auch in knooing alle Rollen. Niemand muss daran denken, und keine alten Zugänge bleiben offen.

Beispiel: Die Beispiel GmbH führt ihre Beschäftigten in ihrem Identity-Provider. Julia Beispiel soll knooing daran anschließen.

Schritt 2: Ein SCIM-Token anlegen

Oben im Reiter steht die Basis-Adresse für Ihr Verzeichnis (i). Tragen Sie darunter bei Bezeichnung ein, welches Verzeichnis das Token nutzt (1), im Beispiel „Verzeichnis Beispiel GmbH“. Lassen Sie bei Gültigkeit 365 Tage stehen und klicken Sie auf Token anlegen (2).

i12

Warum eine Gültigkeit? Ein Token, das abläuft, kann nicht jahrelang unbemerkt weiterwirken. Rechtzeitig vor Ablauf rotieren Sie es, wie unten beschrieben.

Beispiel: Julia Beispiel nennt das Token „Verzeichnis Beispiel GmbH“ und lässt es ein Jahr gelten.

Schritt 3: Token und Basis-Adresse weitergeben

Danach öffnet sich der Dialog Ihr neues Token. Klicken Sie auf Kopieren (1). knooing meldet „Das Token wurde in die Zwischenablage kopiert.“ Fügen Sie das Token sofort in Ihren Passwort-Tresor ein. Klicken Sie erst dann auf Ich habe das Token gesichert (2).

12

Geben Sie das Token über den Passwort-Tresor an die Person weiter, die Ihren Identity-Provider betreut. Markieren Sie auch die Basis-Adresse oben im Reiter, kopieren Sie sie und geben Sie sie mit. Diese Person hat meist keinen Zugang zu knooing und braucht beides.

Danach steht das Token in der Liste (i), mit Status Aktiv, bei Läuft ab dem Datum in einem Jahr und bei Zuletzt genutzt „nie“.

i

Warum sofort kopieren? knooing zeigt das Token nur jetzt. Geht es verloren, legen Sie ein neues an und widerrufen das alte.

Beispiel: Julia Beispiel legt Token und Basis-Adresse im Passwort-Tresor ab und schickt Tobias Beispiel, der den Identity-Provider betreut, den Hinweis darauf.

Schritt 4: Das Token im Identity-Provider eintragen

Diesen Schritt erledigt die Person, die Ihren Identity-Provider betreut. Sie trägt dort im SCIM-Client die Basis-Adresse und das Token ein; wie die Felder heißen, hängt vom Identity-Provider ab. Dafür braucht knooing je Person mindestens die E-Mail-Adresse und eine feste Kennung (externalId). Dann wählt sie die Personen und Gruppen, die an knooing gehen sollen, und startet die Übertragung. Wann die erste Lieferung ankommt, bestimmt der Identity-Provider.

Danach legt knooing die gelieferten Personen und Gruppen an. Im Reiter SCIM-Tokens steht bei Zuletzt genutzt jetzt der Zeitpunkt der letzten Lieferung. So sehen Sie, dass der Identity-Provider liefert.

Was neue Personen erleben: knooing schickt ihnen keine Einladung per E-Mail. Sie melden sich über die Föderation an, also mit dem Konto Ihres Identity-Providers. Ist die Föderation noch nicht eingerichtet, klären Sie den Anmeldeweg mit Ihrem Ansprechpartner bei knooing.

Meldet der Identity-Provider später, dass jemand das Unternehmen verlassen hat, entzieht knooing dieser Person alle Rollen in Ihrem Unternehmen, auch die von Hand vergebenen. Das Konto bleibt bestehen, hat aber keine Rollen mehr. Das gilt immer, auch wenn der Rollenentzug bei Gruppenwegfall aus ist. Was passiert, wenn jemand nur eine Gruppe verlässt, steht im zweiten Teil.

Warum nur ausgewählte Gruppen? knooing braucht nur die Personen, die damit arbeiten. Je weniger übertragen wird, desto kleiner ist das Risiko.

Beispiel: Tobias Beispiel überträgt die Gruppe GG-Lager-Nord mit Paul Beispiel, der neu im Lager arbeitet.

Schritt 5: Die gelieferten Gruppen prüfen

Klicken Sie auf den Reiter Gruppen und Rollen. Unter Gruppen aus dem Verzeichnis steht jede gelieferte Gruppe mit der Zahl ihrer Mitglieder (i). Bei Zugeordnete Rollen steht noch keine Zuordnung: Die Gruppe ist angekommen, vergibt aber noch keine Rolle. Den Knopf Jetzt abgleichen über der Tabelle erklärt der zweite Teil.

i

Klicken Sie dann auf den Reiter Protokoll. Dort steht jeder Aufruf Ihres Identity-Providers (i). POST /Users → 201 heißt: Das Verzeichnis hat eine Person geschickt, und knooing hat sie angelegt (201). POST /Groups → 201 heißt dasselbe für eine Gruppe; dazu steht Gruppe angelegt mit dem Gruppennamen. Ganz unten steht Token angelegt aus Schritt 2. Welche Person kam, zeigt das Protokoll nicht; die neue Person finden Sie unter Nutzer & Rechte, Benutzer, im Beispiel Paul Beispiel.

i

Warum das Protokoll? Es zeigt, ob und wann der Identity-Provider liefert. Die Einträge stammen aus dem Sicherheitsprotokoll und lassen sich nicht verändern.

Beispiel: Julia Beispiel sieht die Gruppe GG-Lager-Nord mit einem Mitglied. Im nächsten Teil ordnet sie ihr die Rolle Lagerteam zu.

Ein Token rotieren oder widerrufen

Ein Token gilt höchstens ein Jahr; das Datum steht in der Liste bei Läuft ab. Klicken Sie vor Ablauf in seiner Zeile auf Rotieren. Es öffnet sich der Dialog Token rotieren. Wählen Sie bei Schonfrist für das alte Token, wie lange das alte Token noch gilt: 24 Stunden (vorgewählt), 72 Stunden, 168 Stunden (7 Tage) oder Altes Token sofort widerrufen. Klicken Sie auf Rotieren. knooing legt ein neues Token mit derselben Bezeichnung an und zeigt es einmal an, wie in Schritt 3. Geben Sie es wie dort weiter. Bis zum Ende der Schonfrist stehen beide Tokens in der Liste; das neue erkennen Sie am späteren Zeitpunkt bei Angelegt.

Mit Widerrufen sperren Sie ein Token sofort. Der Identity-Provider kann sich damit nicht mehr anmelden; das lässt sich nicht rückgängig machen.

Wenn etwas nicht klappt

• „Für diese Aktion ist eine frische Anmeldung nötig (höchstens fünf Minuten alt). …“ Ihre Anmeldung ist älter als fünf Minuten. Klicken Sie im Hinweis auf Neu anmelden. Nach der Anmeldung bringt knooing Sie von selbst auf diese Seite zurück; wiederholen Sie dann den Klick.
• „Die Identitätsanbindung verwaltet nur die Mandantenadministration.“ Ihnen fehlt die Mandantenadministration. Bitten Sie die Person, die knooing in Ihrem Unternehmen verwaltet, das Token anzulegen.
• Bei Zuletzt genutzt steht weiter „nie“. Der Identity-Provider nutzt das Token noch nicht. Lassen Sie prüfen, ob Basis-Adresse und Token dort richtig eingetragen sind und die Übertragung läuft.
• Unter Gruppen aus dem Verzeichnis steht „Es wurden noch keine Gruppen geliefert.“ Der Identity-Provider hat noch nichts übertragen, oder das Token ist falsch eingetragen. Prüfen Sie im Reiter Protokoll, ob Aufrufe ankommen. Steht dort kein Aufruf, erreicht der Identity-Provider knooing nicht: Basis-Adresse oder Token sind falsch eingetragen.
• Im Protokoll steht eine andere Zahl als 201. Die Zahl 200 heißt: geändert, etwa ein neuer Name. Die Zahl 409 heißt: Die Person oder Gruppe gibt es in knooing schon in anderer Form, siehe nächster Punkt. Die Zahl 400 heißt: Der Identity-Provider hat unvollständige Angaben geschickt. Lassen Sie die Zuordnung der Felder dort prüfen.
• „Ein Nutzer mit dieser E-Mail-Adresse existiert bereits unter einer anderen externen Identität.“ Diese Meldung zeigt der Identity-Provider für eine Person. Sie hat in knooing schon ein Konto, das nicht aus dem Verzeichnis stammt. knooing kann ein solches Konto nicht mit dem Verzeichnis verknüpfen. Die Person arbeitet mit ihrem bisherigen Konto weiter; ihre Rollen vergeben Sie dort von Hand. Verlässt sie das Unternehmen, entziehen Sie ihre Rollen ebenfalls von Hand, denn das Verzeichnis erreicht dieses Konto nicht.
• Die Person ist angekommen, kann sich aber nicht anmelden. Die Föderation ist nicht eingerichtet. Klären Sie das mit Ihrem Ansprechpartner bei knooing.
• Die Gruppe hat 0 Mitglieder. Der Identity-Provider hat die Gruppe ohne Mitglieder übertragen, oder die Mitglieder sind dort nicht für knooing ausgewählt. Lassen Sie die Auswahl im Identity-Provider prüfen.
• Das Token ist verloren. Legen Sie ein neues an, geben Sie es weiter und widerrufen Sie danach das alte.
• Das Token steht auf Abgelaufen. Seine Gültigkeit ist vorbei. Legen Sie ein neues an; rotieren Sie künftig rechtzeitig vor Ablauf.