elearnio <> Microsoft Graph API (Dienstkonto Integration)

Ziel

Diese Anleitung beschreibt, wie ein dediziertes Microsoft-Dienstkonto in elearnio konfiguriert wird. Das Dienstkonto ermöglicht es elearnio, Outlook-Kalendertermine zu erstellen und zu aktualisieren sowie - optional - Microsoft Teams-Meeting-Links zu generieren, ohne mandantenweiten Zugriff zu benötigen.

Hinweise

• Alle Berechtigungen sind delegiert und beschränken sich ausschließlich auf das Postfach und die Meetings des Dienstkontos.
• Es werden keine Anwendungsberechtigungen (Application Permissions) vergeben.
• Kalender oder Meetings anderer Benutzer:innen sind nicht zugänglich.

Voraussetzungen

Folgende Informationen müssen vor der Konfiguration bereitstehen:

ℹ️ Randnotiz: Das Dienstkonto benötigt ein vollwertiges Microsoft 365-Postfach (Exchange Online-Lizenz). Ist zusätzlich das Feature "Microsoft Teams - Link Erstellung aktivieren" eingeschaltet, braucht das Dienstkonto außerdem eine Teams-Lizenz, da es sonst keine Online-Meetings erstellen kann.

Schritt 1: App-Registrierung in Azure/Entra anlegen

1. Im Azure Portal bzw. Microsoft Entra Admin Center zu Microsoft Entra ID > App-Registrierungen navigieren.
2. Auf + Neue Registrierung klicken.
3. Einen passenden Namen vergeben (z. B. "elearnio Dienstkonto Integration").
4. Bei Unterstützte Kontotypen die Option "Nur Konten in diesem Organisationsverzeichnis" (Single Tenant) auswählen.
5. Bei Plattform Web auswählen - nicht "Single-Page-Anwendung (SPA)".
6. Als Redirect-URI nicht die Academy-URL des Kunden eintragen (das ist die Vorgehensweise für v1/SPA). v2 verwendet stattdessen eine feste, kundenunabhängige Backend-Callback-URL: https://elearnio.net/backend/api/v1/microsoft_oauth/callback
7. Auf Registrieren klicken.
   

Nach der Registrierung auf der Übersichtsseite folgende Werte notieren:

• Anwendungs-ID (Client) → wird in elearnio als Client ID eingetragen
• Verzeichnis-ID (Mandant) → wird in elearnio als Account ID eingetragen

ℹ️ Azure zeigt auf der Übersichtsseite zusätzlich eine Objekt-ID an. Diese wird in elearnio nicht benötigt - nur Anwendungs-ID und Verzeichnis-ID sind relevant.

Schritt 2: Secret erstellen

1. Im Menü auf Zertifikate & Geheimnisse klicken.
2. Unter Geheime Clientschlüssel auf + Neuer geheimer Clientschlüssel klicken.
3. Eine passende Beschreibung vergeben (z. B. "elearnio Secret Key") und die gewünschte Gültigkeitsdauer setzen.
4. Auf Hinzufügen klicken.
5. Den Wert (nicht die ID!) des erzeugten Schlüssels sofort an einen sicheren Ort kopieren - der Wert kann nach Verlassen der Seite nicht erneut angezeigt werden. Dieser Wert wird in elearnio als Secret eingetragen.

ℹ️ Wir empfehlen, die Gültigkeit des Schlüssels auf mindestens 12 Monate zu setzen. Nach Ablauf muss ein neuer Schlüssel erzeugt und in elearnio hinterlegt werden, da die Integration sonst nicht mehr funktioniert.

⚠️ Microsoft informiert hierzu standardmäßig nicht automatisch per E-Mail über das Ablaufdatum - das liegt an Azure/Entra selbst, nicht an elearnio. Bitte intern eine eigene Erinnerung setzen.

Schritt 3: API-Berechtigungen konfigurieren

1. Im Menü auf API-Berechtigungen klicken.
2. Auf + Berechtigung hinzufügen klicken.
3. Microsoft Graph auswählen.
4. Delegierte Berechtigungen auswählen - nicht Anwendungsberechtigungen.
5. Die folgenden Berechtigungen je nach aktivierten Features (siehe Schritt 6) hinzufügen:

ℹ️ offline_access muss nicht separat hinzugefügt werden. Microsoft gewährt diese Berechtigung automatisch, sobald irgendeine andere delegierte Berechtigung zugestimmt wurde - sie ist Voraussetzung für die Ausstellung eines Refresh Tokens (siehe Abschnitt "Token-Verwaltung"), erscheint aber bewusst nicht als eigener Eintrag in der API-Berechtigungen-Liste.

Administratorzustimmung

Je nach den Standardrichtlinien des Mandanten verlangen einige der oben genannten Berechtigungen keine zwingende Administratorzustimmung (z. B. Calendars.ReadWrite, User.Read, User.Read.All, OnlineMeetings.ReadWrite), während andere - insbesondere Place.Read.All - grundsätzlich eine explizite Zustimmung benötigen, da sie über die Daten der anmeldenden Person hinausgehen.

Wir empfehlen trotzdem, für alle konfigurierten Berechtigungen die Administratorzustimmung zu erteilen, bevor die einmalige Anmeldung in Schritt 7 durchgeführt wird:

6. Auf Administratorzustimmung für "[Mandantenname]" erteilen klicken und bestätigen.

Gründe für diese Empfehlung:

• Sie verhindert, dass der einmalige Login-Vorgang in Schritt 7 durch einen Zustimmungsdialog unterbrochen wird, den die anmeldende Person unter Umständen nicht selbst bestätigen darf.
• Microsoft verschiebt zunehmend Berechtigungen, die früher durch einzelne Nutzer:innen selbst zugestimmt werden konnten, hinter eine mandantenweite Pflicht-Administratorzustimmung. Eine bereits erteilte Zustimmung schützt die Integration vor künftigen Unterbrechungen durch solche Richtlinienänderungen bei Microsoft.

Schritt 4: Conditional Access / MFA berücksichtigen

Die Authentifizierung in Schritt 7 erfolgt über einen interaktiven OAuth 2.0-Login mit den echten Zugangsdaten des Dienstkontos. Aus Sicht von Microsoft Entra verhält sich das Dienstkonto dabei wie ein normales, sich anmeldendes Benutzerkonto - nicht wie ein Service Principal, der automatisch von Conditional-Access-Richtlinien ausgenommen ist.

Daraus ergibt sich:

• Eine Standard-MFA-Abfrage beim einmaligen interaktiven Login ist unproblematisch und muss nicht ausgeschlossen werden.
• Richtlinien, die eine wiederholte Anmeldung erzwingen (z. B. "Anmeldehäufigkeit", Geräte- oder Standortbindung), können hingegen problematisch werden: elearnio verlässt sich nach dem einmaligen Login auf einen langlebigen Refresh Token und bietet keinen automatisierten Mechanismus, um eine erneute interaktive Anmeldung selbst durchzuführen. Wird der Refresh Token durch eine solche Richtlinie vorzeitig invalidiert, muss eine administrierende Person den Login-Vorgang manuell wiederholen.

Empfehlung: Das Dienstkonto wie andere Integrations- bzw. Automatisierungskonten behandeln und - falls im Unternehmen üblich - von Richtlinien ausschließen, die eine wiederholte interaktive Anmeldung erzwingen. Die endgültige Entscheidung liegt beim jeweiligen IT-/Sicherheitsteam des Kunden.

Schritt 5: Integration in elearnio anlegen

1. Im Admin-Bereich Einstellungen → Integrationen aufrufen.
2. Auf Neue Integration hinzufügen klicken.
3. Folgende Pflichtfelder ausfüllen:

Schritt 6: Features aktivieren

Es stehen vier unabhängige Features zur Verfügung. Alle vier sowie das Feld Präfix des Kalendereintrags sind unabhängig vom Status der einzelnen Features sichtbar.

6.1 Microsoft Outlook Integration aktivieren

Was passiert: elearnio erstellt und aktualisiert Kalendertermine im Outlook-Kalender des Dienstkontos. Trainer:innen und Teilnehmende werden automatisch als Teilnehmer hinzugefügt.

Benötigte Berechtigungen (siehe Schritt 3): User.Read, User.Read.All, Calendars.ReadWrite

Präfix des Kalendereintrags: Optionales Feld, das jedem von dieser Integration erstellten Kalendertermin als Präfix vorangestellt wird (z. B. [elearnio] ). Nützlich, um Termine verschiedener Integrationen oder Mandanten im Kalender des Dienstkontos auseinanderzuhalten.

6.2 Microsoft Teams - Link Erstellung aktivieren

Was passiert: Für Kalendertermine wird automatisch ein Microsoft Teams-Meeting-Link generiert. Trainer:innen werden dabei als Co-Hosts des Meetings eingetragen.

Benötigte Berechtigungen (siehe Schritt 3): Calendars.ReadWrite, OnlineMeetings.ReadWrite

6.3 Verfügbarkeitsprüfung aktivieren

Was passiert: Verfügbarkeitsprüfung von Trainer:innen für Termine.

Benötigte Berechtigungen: Keine zusätzlichen - nutzt dieselben Berechtigungen wie Microsoft Outlook Integration (User.Read, User.Read.All, Calendars.ReadWrite).

6.4 Meeting Räume buchen aktivieren

Was passiert: Ressourcenplanung / Raumbuchung über Microsoft.

Benötigte Berechtigungen (siehe Schritt 3): Place.Read.All

Schritt 7: Authentifizierung durchführen

Die Authentifizierung erfolgt einmalig durch eine administrierende Person mit den Anmeldedaten des Dienstkontos.

Ablauf:

1. Nach dem Speichern der Konfiguration auf Autorisieren klicken, um den OAuth 2.0-Authentifizierungsflow zu starten.
2. Im daraufhin öffnenden Microsoft-Login-Fenster die Anmeldedaten des Dienstkontos eingeben. Eine eventuelle MFA-Abfrage an dieser Stelle ist normal und muss bestätigt werden.
3. elearnio prüft im Hintergrund, ob die authentifizierte Person mit der eingetragenen Dienstkonto E-Mail übereinstimmt.
4. Bei erfolgreicher Authentifizierung werden Access Token und Refresh Token sicher gespeichert.
5. Die Einstellungsseite bleibt geöffnet; eine Benachrichtigung zeigt an, ob die Authentifizierung erfolgreich war.

Hinweis: Die Einstellungsseite bleibt nach dem Speichern geöffnet, damit eventuelle Fehler direkt korrigiert werden können.

Token-Verwaltung

elearnio übernimmt die Token-Verwaltung automatisch:

• Access Tokens werden bei Bedarf erneuert, bevor sie ablaufen.
• Refresh Token Rotation wird unterstützt - der jeweils aktuelle Refresh Token wird automatisch gespeichert.
• Sollte ein Refresh Token abgelaufen sein, erscheint eine Aufforderung zur erneuten Authentifizierung.

Eine manuelle Erneuerung der Tokens ist nicht erforderlich, sofern keine Conditional-Access-Richtlinie (siehe Schritt 4) den Refresh Token vorzeitig invalidiert.

Häufige Fehler