SCIM einrichten

SCIM (System for Cross-domain Identity Management) vereinfacht die Benutzerverwaltung. Es ermöglicht dir, User*innen mithilfe eines Standardprotokolls zwischen verschiedenen Anwendungen zu synchronisieren. Du kannst eine zentrale Informationsquelle nutzen, um alle User*innen zu verwalten. User*innen können aus den Identitätsanbieter zu awork importiert oder aus awork deaktiviert werden. Änderungen an Nutzerinformationen wie Name, Zeitzone oder Userrolle werden automatisch in awork übernommen.

Hauptvorteile und Anwendungsfälle

Die Nutzung von SCIM mit awork bringt viele Vorteile mit sich:

• Einfache Benutzerverwaltung: Du musst dir keine Gedanken über den Import von User*nnen machen. Beim Einrichten von SCIM wählst du aus, welche Informationen synchronisiert werden sollen. Das minimale Setup umfasst Vorname, Nachname und E-Mail. Zusätzlich zu diesen Informationen können auch die bevorzugte Sprache, Zeitzone, awork Userrollen, awork-Teams, Abwesenheitsregion und mehr synchronisiert werden.

• SSO-Integration: SCIM funktioniert am besten mit Single-Sign-On (SSO). User*innen müssen sich nur einmal einloggen und können Sicherheitsmechanismen wie die Multi-Faktor-Authentifizierung (MFA) nutzen. Wenn du nur interne User*innen in deinem Workspace hast, die von deinem Identitätsanbieter verwaltet werden, kannst du alle anderen Anmeldeoptionen außer SSO deaktivieren. Wenn du auch externe User*innen in deinem awork-Workspace hast, kannst du trotzdem die Anmeldung per Passwort zulassen.

Wie funktioniert SCIM?

Wenn du Informationen in awork für einen über SCIM synchronisierten User*in manuell änderst, werden diese Änderungen nicht zurück synchronisiert und können überschrieben werden, sobald die nächste Aktualisierung vom Identitätsanbieter erfolgt.

Um die SCIM-Synchronisation zu nutzen, musst du in deinem Identitätsanbieter eine App erstellen. Hier kannst du konfigurieren, welche Felder synchronisiert werden sollen. Du hast auch die Kontrolle darüber, welche Userinnen synchronisiert werden sollen, indem du Usergruppen oder einzelne Usernnen zur SCIM-App hinzufügst.

Unterstützte Funktionen

• User*in erstellen
• User*in aktualisieren
• User*in deaktivieren
• Rollenzuweisungen von awork User*nnen
• awork-Teamzuweisungen aktualisieren
• awork Abwesenheitsregion aktualisieren
• awork globale Berechtigungsrolle aktualisieren

Anforderungen

Die SCIM-Bereitstellung mit awork erfordert:

• Ein aktives Enterprise-Abonnement
• Eine konfigurierte SSO (OpenID Connect) Integration

Was passiert mit bestehenden User*innen in awork?

Sobald du SCIM in deinem Identitätsanbieter aktivierst, werden vorhandene User*innen von awork abgerufen und mit den bestehenden User*innen in deiner SCIM-App abgeglichen.

• Bestehende User*innen, die anhand der E-Mail übereinstimmen, werden in awork aktualisiert.
• User*innen, die noch nicht existieren, werden importiert.
• Alle anderen User*innen in awork werden nicht aktualisiert.

Beim Import neuer User*innen zu awork erhalten diese keine Einladung zu awork. Du musst den neuen User*innen den Link zu deinem awork-Workspace schicken, damit sie sich direkt mit SSO anmelden können. Achte darauf, genügend ungenutzte Userlizenzen in awork zu haben, damit die User aktiviert werden können.

Wenn ein*e User*in vom Admin reaktiviert wird, dann bekommt diese Person eine E-Mail, die sie über die Reaktivierung informiert.

SCIM für awork einrichten

Die Einrichtung von SCIM umfasst drei Schritte:

1. awork für SCIM vorbereiten
2. awork in deinem Identitätsanbieter einrichten
3. Das Mapping konfigurieren

1. awork für SCIM vorbereiten

1. Melde dich in deinem awork Workspace an.
2. Richte SSO für deinen Workspace ein (falls noch nicht geschehen).
3. Gehe zu Einstellungen (Zahnradsymbol links unten im Hauptmenü) > Integrationen.
4. Klicke auf Integrations-Bibliothek öffnen.
5. Wähle im SCIM-Bereich den Anbieter aus, den du verbinden möchtest.
   Falls dein Anbieter nicht in der Liste zu finden ist, kannst du die generische SCIM-Integration wählen.
6. Bestätige und richte die Integration ein.
7. Es erscheint ein Popup mit einem Bearer Token. Kopiere diesen in deine Zwischenablage. Du brauchst ihn, um deinem Identitätsanbieter Zugriff auf awork zu gewähren.
8. Du solltest jetzt die neue SCIM-Integration in der Integrationsliste sehen und eine neue Client-Anwendung in der Liste darunter mit dem Namen API Access.
   Die Client-Anwendung dient der Authentifizierung des SCIM-Clients und kann genutzt werden, um das Bearer Token neu zu generieren, falls du es erneut kopieren musst. Bitte bearbeite oder lösche diese Client-Anwendung nicht!

2. awork in deinem Identitätsanbieter einrichten

Okta

1. Gehe zu Menü > Applications > Applications
   ​

   

2. Klicke auf Browse App Catalogue

3. Suche nach SCIM 2.0

4. Wähle SCIM 2.0 Test App (OAuth Bearer Token)

5. Klicke auf Add Integration

6. Vergib ein App-Label, z.B. awork SCIM integration, und klicke auf Next

7. Überspringe die Sign-on-Methoden (da wir SAML für SSO nicht unterstützen)

8. Wähle bei Credentials Details im Dropdown Email aus

9. Klicke auf Done

10. Gehe zum Provisioning-Tab und klicke auf Configure API Integration
    ​

    

11. Aktiviere Enable API Integration

12. Gib https://app.awork.com/api/v1/scim im Feld SCIM 2.0 Base Url ein

13. Kopiere das Client Secret aus deiner awork SCIM-Integration ins Feld OAuth Bearer Token

14. Klicke auf Save

OneLogin

Für OneLogin bietet awork eine vordefinierte awork-App, die praktische Standardwerte enthält und auch als SSO-App genutzt werden kann. Du brauchst also nur eine App für SSO und SCIM.

1. Gehe in den Administrationsbereich von OneLogin und öffne Applications > Applications

   

2. Klicke oben rechts auf Add App

3. Suche nach awork im Suchfeld

   

4. Klicke auf die awork.com-App und dann oben rechts auf Click

   

5. Nach dem Speichern siehst du eine Grundkonfiguration, die wir bereits für dich eingerichtet haben. Du kannst diese Konfiguration an deinen Anwendungsfall anpassen.

6. Öffne links den Tab Configuration

   

7. Im Feld Login Url kannst du entweder "https://app.awork.com/login" oder direkt den Link zu deiner Subdomain eintragen, also z.B. "https://deine-subdomain.awork.com/login" (bevorzugt).

   

8. Im Feld awork.com subdomain musst du den Link zu deinem Workspace vor awork.com eintragen, also für https://precious-asteroid.awork.com wäre das precious-asteroid.

   

9. Im Abschnitt API Status kannst du einfach auf Enable klicken.

10. Im Abschnitt SCIM Bearer Token kannst du nun den Token einfügen, den du bei der SCIM-Integration in awork erhalten hast.

    

11. Im Feld SCIM JSON Template kannst du festlegen, welche Informationen aus OneLogin mit awork synchronisiert werden. Die Standardkonfiguration synchronisiert nur E-Mail, Vorname und Nachname und sieht so aus:

{
  "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "userName": "{$parameters.scimusername}",
  "name": {
    "givenName": "{$parameters.firstname}",
    "familyName": "{$parameters.lastname}"
  },
  "emails": [
    {
      "value": "{$parameters.email}",
      "primary": true,
      "type": "work"
    }
  ]
}

12. Du kannst diese Konfiguration erweitern, um weitere Benutzerfelder zuzuordnen. Die verfügbaren Felder findest du im Abschnitt Mappings. Für jedes Feld musst du einen Parameter im Tab Parameters anlegen und den Wert aus OneLogin zuweisen. Kontaktiere uns für weitere Informationen.
13. Gehe anschließend zum Tab Provisioning auf der linken Seite

14. Unter Workflow kannst du das Provisioning aktivieren.
15. Du kannst auch entscheiden, ob vor bestimmten Aktionen eine Admin-Freigabe erforderlich sein soll. Wir empfehlen, diese Optionen nur für die Ersteinrichtung/Tests aktiviert zu lassen.
16. Im Abschnitt Entitlements klicke auf Refresh, um die Benutzerrollen aus awork abzurufen. Hinweis: Die Gastrolle wird hier nicht angezeigt, da sie nur für externe Benutzer genutzt werden kann.
17. Wenn du Standard-Benutzerrollen für deine User in awork festlegen möchtest, gehe zum Tab Rules auf der linken Seite.
18. Klicke auf Add Rule, um eine neue Regel hinzuzufügen.
19. Gib einen Namen ein und füge eine Bedingung für deine Regel hinzu, z.B. "user is in group Admin".
20. Nun kannst du Aktionen hinzufügen, wie z.B. das Setzen der Gruppe in awork. Wichtig ist, dass du vorher das Entitlements-Refresh durchgeführt hast, um alle Benutzerrollen abzurufen. Wähle außerdem From Existing, da Benutzerrollen nur direkt in awork erstellt/aktualisiert werden können. Nach Auswahl einer Rolle nicht vergessen, auf Add zu klicken, sonst wird die Gruppe nicht hinzugefügt. Füge nur eine Gruppe hinzu, da ein awork-Benutzer immer nur eine Rolle haben kann.
21. Klicke auf Save.
22. Wiederhole diese Schritte für alle deine awork-Benutzerrollen.

23. Schließe die Konfiguration ab, indem du oben rechts auf Save klickst.
24. Achtung: Du hast alle Konfigurationen abgeschlossen, um Benutzer zu deiner App hinzuzufügen. Wenn du die Konfiguration testen möchtest, empfehlen wir, einen Testbenutzer zur App hinzuzufügen (unter Benutzer -> Benutzer -> Testbenutzer auswählen -> Anwendungen)

25. Im letzten Schritt kannst du deine Benutzer der App hinzufügen - entweder einzeln oder über Richtlinien (empfohlen).
26. Für Richtlinienzugriff auf die App gehe zum Tab Access auf der linken Seite, wähle die Rollen aus, die zur App hinzugefügt werden sollen.
27. Für individuelle Zuweisungen gehe zu den Benutzerdetails und zum Application-Tab. Hier kannst du eine neue App durch Klick auf das Plus-Symbol oben rechts hinzufügen.
28. Den Provisionierungsverlauf findest du unter Benutzer > Provisioning.
29. Alle Ereignisse der awork-App findest du unter Activity > Events.

Accept: application/scim+json

Microsoft Entra ID (früher Azure AD)

1. Gehe zu Microsoft Entra ID

2. Gehe zu Enterprise Applications

3. Erstelle eine neue Anwendung

4. Klicke in der Entra ID Gallery auf Create your own Application

5. Vergib einen Namen, z.B. awork SCIM

6. Wähle Integrate any other application you didn't find in the gallery aus

7. Klicke auf Create

8. Gehe zur neu erstellten App

9. Gehe zum Provisioning-Tab
   ​

   

10. Bearbeite das Provisioning

11. Setze den Provisioning Mode auf Automatic

12. Setze die Admin-Zugangsdaten

    1. Setze die Tenant-URL auf: https://app.awork.com/api/v1/scim
    2. Setze das Secret Token auf den Token, den du bei der SCIM-Integration in awork bekommen hast
    3. Teste die Verbindung, um zu prüfen, ob das Secret korrekt ist

13. Speichere die Konfiguration. Danach erscheinen zwei weitere Abschnitte

14. Bearbeite die Mappings

    1. Klicke auf Groups. Deaktiviere dieses Feature und speichere. Aktuell unterstützt awork keine Gruppen mit Entra ID.
    2. Gehe zurück zu den Mappings und bearbeite die Users-Mappings
       ​

    

15. Setze Target Object Actions auf alle: Create, Update, Delete

16. Die Standardliste der Mappings enthält bereits die richtigen Zuordnungen für die Pflichtfelder. Die restlichen Mappings müssen gelöscht werden, damit die Synchronisation wie erwartet funktioniert. Die benötigten Mappings von Entra ID Mapping zu customappsso Attribute sind:

    1. userPrincipalName -> userName (userPrincipalName muss auf die E-Mail des Benutzers gesetzt sein)

    2. Switch([IsSoftDeleted], , "False", "True", "True", "False") -> active

    3. mail -> emails[type eq "work"].value

    4. preferredLanguage → preferredLanguage

    5. givenName → name.givenName

    6. surname → name.familyName

    7. Optional kannst du aktuell auch zuordnen: jobTitle → userType (wird als Position in awork angezeigt)

17. Wenn du Abwesenheitsregionen, Benutzerrollen und/oder awork Teams synchronisieren möchtest, musst du die awork SCIM Benutzer-Erweiterung konfigurieren: Aktiviere: "Show advanced options"

18. Klicke auf Edit attribute list for custommapsso. Füge folgende Felder als String hinzu:

    • urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:teams
    • urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:absenceRegion
    • urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:userRole
      ​

    

19. Klicke oben auf Save und gehe zurück zum Mapping

20. Füge für jede Erweiterung, die du nutzen möchtest, ein neues Attribut hinzu

    1. Als Source-Attribut empfehlen wir, den Wert als Textfeld beim Azure-Benutzer als benutzerdefiniertes Feld zu speichern und hier auszuwählen, z.B. awork user role.
    2. Als Target das neu hinzugefügte Extension-Feld wählen, z.B. urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:absenceRegion
    3. Klicke auf Ok, um das neue Attribut-Mapping hinzuzufügen

21. Speichere die Benutzermappings

22. Bearbeite die Einstellungen

    1. Aktiviere Prevent accidental deletion, falls gewünscht. Das verhindert, dass viele Benutzer gleichzeitig gelöscht werden, falls z.B. die falsche Gruppe entfernt wurde. Wir empfehlen eine Zahl wie 50, abhängig von deiner Nutzeranzahl und typischen Gruppengrößen.
    2. Aktiviere Sync only assigned users and groups

23. Setze den Provisioning-Status auf On und speichere

24. Teste das Provisioning für einen einzelnen Benutzer

25. Gehe zum Provisioning-Tab der Enterprise-Anwendung und klicke auf Provision on demand

26. Wähle einen einzelnen Benutzer per E-Mail aus

27. Klicke auf Provision

28. Prüfe die Validierungsergebnisse. Deine Benutzerfelder sollten nun in awork aktualisiert werden.
    ​

    

29. Füge die Gruppen/Benutzer hinzu, die die App nutzen sollen. Für jeden neuen Benutzer wird eine zusätzliche Lizenz benötigt - stelle sicher, dass du genügend awork-Lizenzen gebucht hast.

30. Gehe zum Provisioning-Tab. Klicke auf Benutzer und Gruppen und füge die gewünschten Gruppen und Benutzer hinzu. Gruppen-Zuweisungen sind nur mit einer Entra ID Premium P2 Subscription verfügbar.

31. Gehe zur Provisionierungsübersicht und starte den Provisioning-Job. Dieser läuft alle 40 Minuten und synchronisiert alle Änderungen zwischen Entra ID und awork. Felder, die nicht im Mapping enthalten sind, werden in awork nicht überschrieben.
    ​

    

awork Benutzer-Erweiterungsattribute - Beispiele

Abwesenheitsregionen

Abwesenheitsregion muss ein String-Feld sein, das dem Namen der in awork konfigurierten Abwesenheitsregion entspricht.

Benutzerrollen

Die globale Benutzerrolle für Workspace-weite Berechtigungen kann über die userRole-Erweiterung aktualisiert werden.

• Der Name der Benutzerrolle muss mit dem konfigurierten Namen in awork übereinstimmen.
• Die Namensübereinstimmung ist groß-/kleinschreibungs-empfindlich.
• Die Gastrolle kann nicht zugewiesen werden.
• Ein Benutzer kann nur eine Rolle gleichzeitig haben.
• Es muss immer mindestens ein Admin-Benutzer vorhanden sein.
• Die Benutzerrolle kann nicht entfernt werden.

Lege hier ggf. einen Standardwert fest, wenn du steuern möchtest, welche Standardberechtigung ein neu eingeladener Benutzer haben soll.

Fehlerbehebung Entra ID SCIM Sync

Falls die SCIM-Synchronisation nicht wie erwartet funktioniert, kannst du zur Enterprise App Provisioning Overview gehen und auf View provisioning logs klicken. Dort findest du Informationen über die synchronisierten Benutzer und Eigenschaften. Bei Problemen wird der Status auf Failure gesetzt. Klicke auf den Eintrag, gehe auf Troubleshooting & Recommendations und kopiere die Fehlermeldung. Kontaktiere dann unseren Support und sende die Fehlermeldung, damit wir uns das genauer ansehen können.

3. Das Mapping konfigurieren

Die awork Benutzerfelder werden auf das SCIM Benutzer-Resource gemappt. Eine Liste der unterstützten Felder findest du hier:

Wenn es Felder gibt, die du synchronisieren möchtest, die hier nicht aufgeführt sind, lass es uns bitte wissen.

awork-Benutzerrollen können auf zwei Arten verwaltet werden: entweder über das /Groups-Feature oder die awork-Benutzererweiterung.

• Die awork Benutzererweiterung: Hierfür muss das Erweiterungsattribut auf ein Textfeld des Benutzers (oder ein anderes Feld für den SCIM Sync) gemappt werden, in dem der Name der Benutzerrolle steht (** bevorzugt**)
• Beim SCIM /Groups-Feature: Zuerst müssen die verfügbaren Benutzerrollen synchronisiert werden. Dies geht meist manuell, indem die verfügbaren Gruppen abgerufen und die Gruppen auf Basis definierter Regeln gemappt werden. Beachte, dass ein awork-Benutzer nur eine Benutzerrolle gleichzeitig haben kann. Stelle also sicher, dass du nicht mehr als eine Rolle über die Gruppenzuweisungen zuweist, da diese Einschränkung von SCIM nicht direkt unterstützt wird. Falls eine Rolle umbenannt, eine neue Rollen hinzugefügt oder eine existierende Rolle gelöscht wird, musst du in der Regel die verfügbaren Gruppen manuell neu synchronisieren.

FAQ

Kann ich Benutzerrollen über SCIM erstellen/aktualisieren?

Nein, du kannst Rollen nur zuordnen. Um Berechtigungsrollen in awork zu erstellen oder zu aktualisieren, gehe zu Menü → Einstellungen → Berechtigungen.

Kann ich E-Mail-Adressen über SCIM aktualisieren?

Ja, das Aktualisieren von Account-E-Mails und Benutzer-Kontakt-E-Mails wird über SCIM unterstützt. Die Account-E-Mail für Login und SSO wird über das userName-Attribut aktualisiert.

Einschränkungen:

• Ist der Benutzer in mehreren Workspaces, kann die Account-E-Mail nicht geändert werden. Der Benutzer muss seine E-Mail manuell in den Profileinstellungen aktualisieren.
• Wenn die E-Mail bereits von einem anderen Account genutzt wird, wird ein Fehler zurückgegeben. Um die E-Mail zu verwenden, muss der bestehende Account gelöscht werden. Dies erfolgt, indem du den Benutzer löschst, der mit diesem Account verbunden ist.

Kann ich Profilbilder über SCIM synchronisieren?

Dies wird aktuell von den Anbietern OneLogin und Okta nicht unterstützt. Daher bieten wir diese Funktionalität derzeit generell nicht an.

Was passiert, wenn ich den Namen einer Berechtigungsrolle in awork ändere?

Nachdem du die Berechtigungsrollen in awork umbenannt hast, musst du die Gruppen in deinem SCIM-Client aktualisieren, damit die korrekten Namen angezeigt werden. Die Zuordnung sollte sich nicht ändern, da diese anhand der ID der Benutzerrolle erfolgt und nicht anhand des Anzeigenamens.

Was kann ich tun, wenn meine SCIM-Integration nicht wie erwartet funktioniert?

Überprüfe die Benutzer, die nicht bereitgestellt werden können, und schaue dir die jeweiligen Fehlermeldungen an. Sende unserem Support-Team die Trace-ID, damit wir das für dich prüfen können. Stelle sicher, dass deine Client-Anwendung korrekt eingerichtet ist und auch das API Access-Element (Eintrag in der Liste unter den Integrationen) vorhanden ist. Andernfalls lösche die Integration in awork und versuche, sie erneut einzurichten.

Können Gastbenutzer über SCIM synchronisiert werden?

Gastbenutzer können über die SCIM-Integration nicht erstellt werden, da bei der Benutzererstellung automatisch die Benutzerrolle mit den geringsten Berechtigungen zugewiesen wird, die nicht die Gastrolle ist. Wenn der Benutzer bereits in awork existiert, wird die Rolle über die SCIM-Integration nicht geändert, es sei denn, dies ist explizit über das SCIM-Gruppen-Feature konfiguriert. Bereits bestehende Gastbenutzer können über die SCIM-Integration synchronisiert werden, allerdings unterstützt das SCIM-Gruppen-Feature keine Zuweisung von Gastrollen.