SCIM einrichten

Synchronisiere deine awork-Benutzer automatisch über einen Identity Provider und verwalte Benutzerinformationen zentral.

SCIM (System for Cross-domain Identity Management) vereinfacht die Benutzerverwaltung. Es ermöglicht dir, Benutzer mithilfe eines Standardprotokolls zwischen verschiedenen Anwendungen zu synchronisieren. Du kannst deinen Identity Provider als zentrale Informationsquelle verwenden und Benutzer von dort automatisch in awork anlegen, aktualisieren und deaktivieren.

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.

So funktioniert SCIM

Änderungen, die du bei synchronisierten Usern manuell in awork vornimmst, werden nicht zurück an den Identity Provider übertragen und können bei der nächsten Synchronisierung überschrieben werden.

User werden über userName abgeglichen

awork verwendet das SCIM-Attribut userName als eindeutigen Matching-Key. Der Wert von userName muss der E-Mail-Adresse des awork-Kontos des Users entsprechen.

Für den Abgleich wird externalId nicht verwendet.

Wenn userName von der bestehenden E-Mail-Adresse des awork-Kontos abweicht, wird das bestehende Konto nicht zugeordnet. Stattdessen kann ein weiteres awork-Konto erstellt werden.

Beispiel für Microsoft Entra ID:

• Verwende userPrincipalName für userName, wenn userPrincipalName der E-Mail-Adresse des awork-Kontos entspricht.

• Wenn userPrincipalName nicht der awork-E-Mail-Adresse entspricht, verwende mail oder ein anderes Attribut, das die korrekte E-Mail-Adresse enthält.

Bei anderen Identity Providern:

Ordne das Quellattribut, das die E-Mail-Adresse des awork-Kontos enthält, dem SCIM-Attribut userName zu.

Der Identity Provider ist die führende Quelle

Der Identity Provider ist für synchronisierte Attribute maßgeblich. Nicht-leere Werte, die über SCIM übertragen werden, überschreiben die entsprechenden Werte in awork während der Synchronisierung.

Leere Werte löschen einfache Profilfelder im Allgemeinen nicht.

Welche Daten werden synchronisiert?

Darüber hinaus unterstützt awork weitere SCIM-Attribute und Erweiterungen für E-Mail-Adressen, Telefonnummern, Adressen, Teams, Rollen und Abwesenheitsregionen.

E-Mail-Adressen, Telefonnummern und Adressen werden als vollständige Mengen synchronisiert

E-Mail-Adressen, Telefonnummern und Adressen werden als vollständige Sets synchronisiert.

Das bedeutet: Einträge, die manuell in awork gepflegt werden, werden entfernt, wenn der Identity Provider sie bei der nächsten Synchronisierung nicht übermittelt.

Plane dein Mapping deshalb so, dass alle Einträge, die erhalten bleiben sollen, vom Identity Provider bereitgestellt werden.

Teams, Rollen und SCIM-Gruppen sind unterschiedliche Konzepte

awork-Teams und Berechtigungsrollen sind unterschiedliche Konzepte:

• Teams werden über die benutzerdefinierte teams-Erweiterung als kommagetrennte Liste von awork-Teamnamen zugewiesen.

• Eine Berechtigungsrolle kann über die benutzerdefinierte userRole-Erweiterung zugewiesen werden.

• Sofern unterstützt, stellen SCIM-Gruppen awork-Berechtigungsrollen dar, nicht awork-Teams.

• Jeder Users kann nur eine Berechtigungsrolle haben.

• Das Entfernen eines Users aus einer SCIM-Gruppe entfernt oder reduziert dessen awork-Rolle nicht. Weise stattdessen eine andere Rolle zu oder deaktiviere den User.

• Teams und Rollen müssen bereits in awork vorhanden sein. SCIM erstellt sie nicht automatisch.

Namen müssen exakt übereinstimmen

Die Werte in teams, userRole und absenceRegion müssen exakt mit den bereits in awork vorhandenen Namen übereinstimmen.

Unbekannte Teamnamen führen dazu, dass die Bereitstellung fehlschlägt. Diese Ressourcen werden nicht automatisch erstellt.

Die Namensübereinstimmung ist groß-/kleinschreibungs-empfindlich.

Folgende Einschränkungen gelten zusätzlich:

• Gastrollen können nicht über SCIM zugewiesen werden.

• Archivierte Rollen können nicht zugewiesen werden.

• Der letzte Administrator kann nicht deaktiviert werden.

• Eine Rolle kann nicht einfach entfernt werden.

• Eine Abwesenheitsregion kann über die Erweiterung geändert, aber nicht entfernt werden.

Deaktivierung und Reaktivierung

SCIM löscht einen awork-User niemals dauerhaft.

Eine SCIM-Delete-Anfrage oder active=false deaktiviert den User. Seine Aufgaben, Zeiteinträge, Kommentare und andere Daten bleiben erhalten.

Wenn der Identity Provider später active=true sendet, reaktiviert awork das bestehende Konto und sendet dem Benutzer eine Aktivierungs-E-Mail.

E-Mail-Adressen können über SCIM aktualisiert werden

SCIM kann Kontoinformationen aktualisieren, nachdem der User die Einladung zum Workspace angenommen hat.

User, die über SCIM erstellt wurden, werden automatisch freigegeben.

Eine Änderung der E-Mail-Adresse schlägt fehl, wenn die neue Adresse bereits einem anderen awork-Konto zugeordnet ist.

Lizenzen und automatische Buchung

Für jeden aktivierten User wird eine entsprechende awork-Lizenz benötigt.

Wenn keine Lizenz verfügbar ist, schlägt die Bereitstellung fehl, sofern die automatische SCIM-Sitzplatzbuchung nicht aktiviert ist.

Wenn die automatische SCIM-Userbuchung aktiviert ist, bucht awork automatisch die benötigte Sitzplatz. Die zugehörige Rechnung wird ungefähr 30 Minuten später erstellt.

Die Einstellung findest du in deinem Workspace unter:

Einstellungen → Workspace → Workspace-Einstellungen → Automatische User-Buchungen über SCIM erlauben

Externe Benutzer

awork-Connect-User sind von SCIM ausgeschlossen und bleiben über ihren eigenen Workspace verwaltet.

Klassische Gastuser innerhalb eines Workspaces sind davon zu unterscheiden. Sie können von den Anmeldebeschränkungen des Workspaces betroffen sein.

Prüfe diese User deshalb vor der Durchsetzung einer reinen SSO-Anmeldung und migriere sie nach Möglichkeit zu awork-Connect-Usern.

Voraussetzungen

Die SCIM-Bereitstellung mit awork erfordert:

• ein aktives Enterprise-Abonnement

• eine konfigurierte SSO-Integration über OpenID Connect

Für OneLogin bietet awork eine vorkonfigurierte App, die SCIM und SSO (OpenID Connect) in einer einzigen App integriert.

Außerdem müssen ausreichend ungenutzte awork-Lizenzen vorhanden sein, sofern die automatische SCIM-Userbuchung nicht aktiviert ist.

Was passiert mit bestehenden Usern?

Wenn du SCIM in deinem Identity Provider aktivierst, werden bestehende User anhand ihres userName-Werts mit den Accounts in awork abgeglichen.

Damit ein bestehender awork-Account erkannt wird, muss userName exakt der Account-E-Mail des Benutzers entsprechen.

• Bestehende Benutzer mit übereinstimmendem userName werden aktualisiert.
• User, die noch nicht in awork existieren, werden importiert.
• Andere User in awork, die nicht Teil des SCIM-Synchronisierungsumfangs sind, werden nicht verändert.

SCIM kann auch nur für einen Teil der User verwendet werden. User außerhalb des Synchronisierungsumfangs bleiben davon unberührt.

SCIM für awork einrichten

Die Einrichtung besteht aus drei Schritten:

1. awork für SCIM vorbereiten

2. SCIM im Identity Provider einrichten

3. Das Mapping konfigurieren

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. Öffne die Integrations-Bibliothek.

5. Wähle im SCIM-Bereich den Anbieter aus, den du verbinden möchtest.

6. Wenn dein Anbieter nicht aufgeführt ist, verwende die generische SCIM-Integration.

7. Bestätige und richte die Integration ein.

8. Nach der Einrichtung wird ein Bearer Token angezeigt. Kopiere ihn und bewahre ihn sicher auf. Du benötigst ihn für die Konfiguration deines Identity Providers.

9. Anschließend siehst du die SCIM-Integration in der Integrationsliste sowie eine Client-Anwendung mit dem Namen API Access.

Die Client-Anwendung dient der Authentifizierung des SCIM-Clients. Über sie kann bei Bedarf ein neues Bearer Token generiert werden.

SCIM im Identity Provider einrichten

Okta

1. Gehe in Okta zu Applications → Applications.

2. Klicke auf Browse App Catalog.

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, zum Beispiel awork SCIM integration, und klicke auf Next.

7. Überspringe die Sign-on-Einstellungen.

8. Wähle bei den Credential Details Email.

9. Klicke auf Done.

10. Öffne den Tab Provisioning und klicke auf Configure API Integration.

11. Aktiviere Enable API Integration.

12. Trage folgende URL als SCIM Base URL ein:

https://app.awork.com/api/v1/scim

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

14. Speichere die Konfiguration.

User-Mapping in Okta

Ordne die Userfelder so zu, dass userName die E-Mail-Adresse des awork-Accounts enthält.

Beispielsweise:

Weitere Attribute kannst du entsprechend dem unterstützten Mapping ergänzen.

Achte besonders darauf, dass der für userName verwendete Wert mit der E-Mail-Adresse des awork-Accounts übereinstimmt.

OneLogin

Für OneLogin bietet awork eine vorkonfigurierte awork.com-App, die praktische Standardwerte enthält und auch für SSO verwendet werden kann. Dadurch können SCIM und SSO mit einer App eingerichtet werden.

1. Öffne im OneLogin-Administrationsbereich Applications → Applications.

2. Klicke auf Add App.

3. Suche nach awork.

4. Wähle die awork.com-App aus.

5. Speichere die App.

6. Öffne den Tab Configuration.

Allgemeine Konfiguration

Im Feld Login URL kannst du entweder

https://app.awork.com/login

oder bevorzugt die Login-URL deiner Workspace-Subdomain verwenden, zum Beispiel:

https://deine-subdomain.awork.com/login

Im Feld awork.com subdomain trägst du den Teil deiner Workspace-URL vor .awork.com ein.

Beispiel:

https://precious-asteroid.awork.com

→ precious-asteroid

Aktiviere anschließend im Bereich API Status die API.

Füge unter SCIM Bearer Token den Token ein, den du bei der SCIM-Integration in awork erhalten hast.

SCIM JSON Template

Mit dem SCIM JSON Template legst du fest, welche Informationen OneLogin an awork übermittelt.

Eine minimale Konfiguration kann beispielsweise so aussehen:

{
  "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"
    }
  ]
}

Weitere Benutzerfelder kannst du über die Mappings und zusätzlichen Parameter ergänzen.

Rollen in OneLogin

1. Öffne den Tab Provisioning.

2. Aktiviere das Provisioning.

3. Unter Entitlements kannst du mit Refresh die verfügbaren awork-Rollen abrufen.

4. Die Gastrolle wird hier nicht angezeigt, da sie ausschließlich für externe Benutzer verwendet werden kann.

5. Verwende unter Rules Regeln, um Benutzern eine Berechtigungsrolle zuzuweisen.

6. Ein Benutzer kann immer nur eine awork-Berechtigungsrolle haben.

Wenn du mehrere Rollen in OneLogin abbildest, stelle sicher, dass eine Person nicht gleichzeitig mehreren awork-Rollen zugeordnet wird.

Accept: application/scim+json

Microsoft Entra ID

1. Enterprise Application erstellen

1. Öffne Microsoft Entra ID.

2. Gehe zu Enterprise Applications.

3. Erstelle eine neue Anwendung.

4. Wähle Create your own application.

5. Vergib beispielsweise den Namen awork SCIM.

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

7. Klicke auf Create.

8. Öffne die neu erstellte Anwendung.

9. Gehe zum Tab Provisioning.

10. Klicke auf Edit provisioning.

11. Setze den Provisioning Mode auf Automatic.

2. Admin-Zugangsdaten konfigurieren

Trage unter Admin Credentials Folgendes ein:

Tenant URL

https://app.awork.com/api/v1/scim

Secret Token

Verwende den Bearer Token aus deiner awork-SCIM-Integration.

Teste anschließend die Verbindung und speichere die Konfiguration.

3. Gruppen deaktivieren

Die Gruppenbereitstellung in Entra ID sollte für awork deaktiviert werden.

Verwende stattdessen:

• die userRole-Erweiterung zur Verwaltung von Berechtigungsrollen

• die teams-Erweiterung zur Verwaltung von Teams

Diese Einschränkung gilt speziell für die Entra-Konfiguration.

4. User-Mappings konfigurieren

Setze bei den Target Object Actions mindestens:

• Create

• Update

• Delete

Lösche nicht benötigte Standard-Mappings, damit nur die gewünschten Attribute synchronisiert werden.

Empfohlene Standard-Mappings

Wichtig für userName: Verwende userPrincipalName nur dann als Quelle für userName, wenn userPrincipalName der E-Mail-Adresse des awork-Accounts entspricht.

Wenn diese Werte voneinander abweichen, verwende mail oder ein anderes Entra-Attribut, das die korrekte awork-Account-E-Mail enthält.

Beispiel:

• userPrincipalName: max.mustermann@unternehmen.de

• awork-Account-E-Mail: max.mustermann@firma.de

In diesem Fall darf userPrincipalName nicht für userName verwendet werden. Stattdessen muss ein Attribut mit max.mustermann@firma.de zugeordnet werden.

5. awork-Erweiterungsattribute konfigurieren

Wenn du Teams, Rollen oder Abwesenheitsregionen synchronisieren möchtest, musst du die awork-SCIM-Benutzererweiterung verwenden.

Aktiviere dazu Show advanced options und öffne Edit attribute list for customappsso.

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

Speichere die Attribute und kehre zu den User-Mappings zurück.

Für jedes Attribut, das du verwenden möchtest:

1. Füge ein neues Mapping hinzu.

2. Wähle als Source Attribute das entsprechende Entra-Attribut.

3. Wähle als Target das passende awork-Erweiterungsattribut.

4. Speichere das Mapping.

Am einfachsten ist es, die Werte für Teams, Rollen und Abwesenheitsregionen in einem eigenen Textfeld des Entra-Benutzers zu hinterlegen.

6. Teams, Rollen und Abwesenheitsregionen in Entra verwalten

Teams

Das Attribut

urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:teams

erwartet eine kommagetrennte Liste von awork-Teamnamen.

Beispiel:

Marketing, Vertrieb, Product

Die Teamnamen müssen in awork bereits vorhanden sein und exakt übereinstimmen.

Berechtigungsrollen

Das Attribut

urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:userRole

erwartet den Namen einer bereits vorhandenen awork-Berechtigungsrolle.

Ein User kann nur eine Berechtigungsrolle haben.

Abwesenheitsregion

Das Attribut

urn:ietf:params:scim:schemas:extension:awork.com:2.0:User:absenceRegion

erwartet den Namen einer bereits vorhandenen Abwesenheitsregion.

Eine Abwesenheitsregion kann über SCIM geändert, aber nicht entfernt werden.

7. Provisioning-Einstellungen in Entra

Unter Settings kannst du Prevent accidental deletion aktivieren.

Diese Einstellung kann verhindern, dass bei einer Fehlkonfiguration versehentlich viele Benutzer gleichzeitig deaktiviert werden. Wähle einen Grenzwert, der zu deiner Benutzeranzahl und deiner üblichen Gruppengröße passt.

Aktiviere außerdem: Sync only assigned users and groups

Anschließend:

1. Setze den Provisioning Status auf On.

2. Speichere die Konfiguration.

3. Teste die Bereitstellung zunächst für einen einzelnen Benutzer.

8. Provisioning testen

Verwende in Entra die Funktion Provision on demand.

1. Wähle einen einzelnen Testbenutzer aus.

2. Starte Provision.

3. Prüfe die Validierungsergebnisse.

4. Kontrolliere anschließend den Benutzer in awork.

Prüfe mindestens:

• E-Mail-Adresse

• Vorname

• Nachname

• Position

• Sprache

• Zeitzone

• Berechtigungsrolle

• Teams

• Abwesenheitsregion

• Aktivierungsstatus

Erst wenn der Test erfolgreich ist, solltest du den vollständigen Benutzerkreis für die Anwendung freigeben.

9. Benutzer und Gruppen zuweisen

Füge anschließend die Benutzer und Gruppen hinzu, die die Enterprise Application verwenden sollen.

Für neue User wird eine awork-Lizenz benötigt. Stelle sicher, dass ausreichend Lizenzen vorhanden sind oder die automatische SCIM-Userbuchung aktiviert ist.

Unter Provisioning → Users and Groups kannst du den Synchronisierungsumfang festlegen.

Die von Entra verwendete Provisionierung synchronisiert die Änderungen anschließend automatisch.

Mapping-Referenz

Die folgenden Attribute werden von awork unterstützt:

Migrations-Checkliste

Bevor du SCIM für viele User aktivierst, empfehlen wir folgende Prüfung:

1. Exportiere oder vergleiche die Benutzerlisten von awork und deinem Identity Provider.

2. Stelle sicher, dass die gewählte Quelle für userName bei jedem Benutzer exakt der E-Mail-Adresse des awork-Kontos entspricht.

3. Behebe alle Abweichungen, bevor du Provisioning aktivierst.

4. Erstelle alle benötigten Rollen, Teams und Abwesenheitsregionen bereits in awork.

5. Teste das Provisioning zunächst mit einem User, der kein Administrator ist.

6. Prüfe E-Mail-Adresse, Profil, Rolle, Teams und Aktivierungsstatus.

7. Teste Deaktivierung und anschließende Reaktivierung.

8. Erweitere den Zuweisungsumfang im Identity Provider erst nach erfolgreichem Test.

9. Halte während der gesamten Einführung mindestens einen awork-Administrator aktiv.

Fehlerbehebung

Wenn die SCIM-Synchronisierung nicht wie erwartet funktioniert, prüfe zunächst die Provisioning- bzw. Synchronisierungsprotokolle deines Identity Providers.

Achte insbesondere auf Fehler bei:

• userName

• unbekannten Rollen oder Teams

• nicht verfügbaren Lizenzen

• ungültigen SCIM-Erweiterungsattributen

• mehreren zugewiesenen Rollen

• Deaktivierung eines Administrators

Wenn ein Fehler weiterhin besteht, sende dem awork-Support die entsprechende Fehlermeldung und – sofern vorhanden – die Trace-ID des fehlgeschlagenen Synchronisierungsvorgangs.

FAQ

Kann ich Benutzerrollen über SCIM erstellen?

Nein. Über SCIM können bestehende awork-Berechtigungsrollen Benutzern zugewiesen werden. Rollen selbst müssen zuvor in awork erstellt werden.

Kann ich Teams über SCIM erstellen?

Nein. Teams müssen bereits in awork existieren. SCIM weist User bestehenden Teams zu.

Können E-Mail-Adressen über SCIM aktualisiert werden?

Ja. SCIM kann die Account-E-Mail und weitere Kontakt-E-Mail-Adressen aktualisieren. Die Account-E-Mail wird über userName gesteuert. Damit ein bestehendes Konto korrekt erkannt wird, muss userName zunächst dessen aktuelle awork-Konto-E-Mail enthalten. Eine Änderung der E-Mail-Adresse schlägt fehl, wenn die neue Adresse bereits einem anderen awork-Konto zugeordnet ist.

Wird externalId für den Benutzerabgleich verwendet?

Nein. awork verwendet userName als eindeutigen Matching-Key. Der Wert muss der Account-E-Mail des Users entsprechen.

Was passiert, wenn ich einen User über SCIM lösche?

Ein SCIM-Delete löscht den User nicht dauerhaft. Der User wird deaktiviert. Aufgaben, Zeiteinträge, Kommentare und andere Daten bleiben erhalten.

Was passiert bei active=false?

Der User wird deaktiviert. Seine Daten bleiben erhalten.

Was passiert bei active=true?

awork reaktiviert das bestehende Konto und sendet dem User eine Aktivierungs-E-Mail.

Kann ich einen User manuell in awork bearbeiten?

Ja, Änderungen können manuell vorgenommen werden. Bei synchronisierten Attributen können diese Änderungen jedoch bei der nächsten Synchronisierung durch Werte des Identity Providers überschrieben werden.

Was passiert mit manuell gepflegten E-Mail-Adressen, Telefonnummern und Adressen?

Diese Attribute werden als vollständige Mengen synchronisiert. Ein Eintrag, den der Identity Provider nicht mitsendet, kann daher bei der nächsten Synchronisierung aus awork entfernt werden.

Können Gastrollen über SCIM zugewiesen werden?

Nein. Die Gastrolle kann nicht über SCIM zugewiesen werden.

Kann ich die Berechtigungsrolle eines Users entfernen?

Nein. Eine Berechtigungsrolle kann nicht einfach entfernt werden. Weise stattdessen eine andere Rolle zu oder deaktiviere den User.

Kann der letzte Administrator deaktiviert werden?

Nein. Es muss immer mindestens ein aktiver Administrator vorhanden sein.

Kann eine Abwesenheitsregion entfernt werden?

Nein. Eine Abwesenheitsregion kann über SCIM geändert, aber nicht entfernt werden.

Was passiert, wenn ein Team oder eine Rolle in awork umbenannt wird?

Die Werte im Identity Provider müssen weiterhin exakt mit den in awork vorhandenen Namen übereinstimmen. Aktualisiere deshalb nach einer Umbenennung die entsprechenden Werte im Identity Provider.

Können awork Connect-User über SCIM verwaltet werden?

Nein. awork Connect-Benutzer sind von SCIM ausgeschlossen und werden über ihren eigenen Workspace verwaltet.