Microsoft Entra synchronisieren

Mit der HRIS-Synchronisierung importiert onyo Deine Mitarbeitenden automatisch aus Microsoft Entra (früher Azure AD genannt) – stündlich und ohne manuellen Import. Diese Anleitung führt Dich Schritt für Schritt durch die Einrichtung.

Voraussetzung: In Microsoft Entra brauchst Du die Rechte, eine App-Registrierung anzulegen und Administratorzustimmung zu erteilen (z.B. als Administrator Eures Microsoft-365-Mandanten).

Schritt 1: In onyo den Anbieter auf Microsoft Entra setzen

Öffne in onyo die Seite HRIS-Synchronisierung (Einstellungen → Allgemeines → HRIS-Synchronisierung) und wähle unter „HRIS-Anbieter“ den Eintrag Microsoft Entra aus. Es erscheinen die drei Felder „Entra Verzeichnis-ID (Mandant)“, „Entra Anwendungs-ID (Client)“ und „Entra Client-Secret“ – die Werte dafür holen wir in den Schritten 2–4 aus Microsoft Entra.

Schritt 2: In Microsoft Entra eine Anwendung registrieren

Öffne im Microsoft Entra Admin Center die Seite „Anwendung registrieren“ (zu finden unter Entra ID → App-Registrierungen → „Neue Registrierung“). Trage als Name z.B. onyo ein, behalte bei „Unterstützte Kontotypen“ die Option „Nur ein Mandant“ und klicke auf „Registrieren“. Eine Umleitungs-URI ist für die Synchronisierung nicht nötig.

Schritt 3: Tenant-ID und Client-ID kopieren

Nach der Registrierung landest Du auf der „Übersicht“ der Anwendung. Kopiere dort die „Verzeichnis-ID (Mandant)“, wechsle zurück zur onyo-Einstellungsseite und füge sie in das Feld „Entra Verzeichnis-ID (Mandant)“ ein. Geh anschließend zurück zur Entra-Übersicht und mach dasselbe mit der „Anwendungs-ID (Client)“ für das onyo-Feld „Entra Anwendungs-ID (Client)“.

Schritt 4: Client-Secret erstellen

Gehe im Menü der Anwendung zu „Zertifikate & Geheimnisse“ und klicke auf „Neuer geheimer Clientschlüssel“. Vergib eine Beschreibung (z.B. „onyo HRIS-Synchronisierung“), wähle eine Gültigkeitsdauer und klicke auf „Hinzufügen“. Kopiere den Wert des Schlüssels sofort in das onyo-Feld „Entra Client-Secret“ – er wird nur einmal angezeigt.

Wenn der Schlüssel abläuft, stoppt die Synchronisierung: Erstelle dann einfach einen neuen Schlüssel und trage ihn in onyo ein.

Schritt 5: API-Berechtigungen vergeben

Gehe zu „API-Berechtigungen“ → „Berechtigung hinzufügen“ → Microsoft Graph → „Anwendungsberechtigungen“ und füge die beiden Berechtigungen User.Read.All und GroupMember.Read.All hinzu. Klicke anschließend auf „Administratorzustimmung für … erteilen“ und bestätige, sodass in der Spalte „Status“ ein grünes „Gewährt für …“ erscheint.

onyo nutzt User.Read.All, um die Mitarbeitenden zu importieren, und GroupMember.Read.All, um Eure Gruppen und ihre Mitglieder zu lesen. (Alternativ genügt User.ReadBasic.All statt User.Read.All – dann werden aber nur Namen und E-Mail-Adressen importiert, ohne Adressen, und in Entra deaktivierte Konten werden nicht in onyo deaktiviert.)

Schritt 6: Zugangsdaten in onyo speichern

Wechsle zurück zu onyo. Die drei Felder aus Schritt 1 sollten jetzt ausgefüllt sein – klicke auf „Änderungen speichern“.

Schritt 7: Synchronisierung einstellen

Nach dem Speichern wird die Gruppenliste live aus Microsoft Entra geladen. Lege unter „2. Synchronisierung“ fest, welche Mitarbeitenden importiert werden:

• Beschäftigungsstatus – nur Mitarbeitende mit diesen Status importieren.
• Beschäftigungsart – nur Mitarbeitende mit diesen Beschäftigungsarten importieren.
• HRIS-Gruppen – nur Mitglieder der gewählten Entra-Gruppen importieren. Leer lassen, um alle aktuellen und zukünftigen Gruppen einzubeziehen. Viele Firmen legen in Entra eine eigene Gruppe (z.B. „onyo“) an und wählen nur diese aus.
• Budgetfeld in Tokens – für die meisten Firmen irrelevant und nur relevant, wenn Ihr in onyo mit virtuellen Tokens statt Euro arbeitet. Nur dann und nur, wenn das Budget in Entra ebenfalls in Tokens gepflegt ist, aktivieren.

Wichtig: Setzt Du mehrere Filter, müssen Mitarbeitende alle davon erfüllen, um importiert zu werden. Wählst Du z.B. bestimmte Beschäftigungsstatus und bestimmte Beschäftigungsarten aus, wird jemand nur importiert, wenn sowohl der Status als auch die Beschäftigungsart passt (und, falls Gruppen gewählt sind, die Person zu einer davon gehört). Innerhalb eines einzelnen Filters genügt dagegen ein Treffer – etwa einer der ausgewählten Status.

Klicke anschließend auf „Änderungen speichern“.

Schritt 8: Erste Synchronisierung starten

Klicke oben auf „Jetzt mit Microsoft Entra synchronisieren“, um den ersten Import zu starten. Danach synchronisiert onyo automatisch jede Stunde.

Geschafft :) Ab jetzt hält onyo Deine Mitarbeitenden automatisch mit Microsoft Entra in Einklang: Neue Personen werden in onyo angelegt, Änderungen (z.B. Name oder Adresse) übernommen und Personen, die nicht mehr Deinen Kriterien entsprechen oder in Entra gelöscht wurden, deaktiviert – stündlich und ohne manuellen Import. Solltest Du Fragen oder Probleme haben, wende Dich gerne jederzeit über das Kontaktformular an uns.

Tipp: Ihr könnt dieselbe Entra-Anwendung auch für Single Sign-On verwenden. Die Anwendung braucht dann beide Berechtigungssätze: die Anwendungsberechtigungen aus dieser Anleitung und zusätzlich die delegierten Berechtigungen „openid“ und „email“.