Automatische Secret-Erneuerung

Überblick

Die Verbindung zwischen RELion und Archiv kompakt (Cloud-Modus) wird über eine Microsoft Entra-Anwendung mit einem geheimen Schlüssel (Secret) abgesichert. Dieses Secret hat ein Ablaufdatum. Läuft es ab, ohne rechtzeitig erneuert zu werden, bricht die Verbindung zu Archiv kompakt ab.

Das Feature RelAAK Secret Renewal übernimmt diese Erneuerung automatisch:

• RELion prüft täglich, wann das aktuell hinterlegte Secret abläuft.
• Läuft es innerhalb der nächsten 21 Tage ab, erzeugt RELion automatisch ein neues Secret in Microsoft Entra ID, überträgt es an Archiv kompakt und übernimmt es anschließend selbst.
• Ein Administrator muss dafür einmalig Voraussetzungen einrichten, danach läuft die Erneuerung ohne weiteres Zutun.

Voraussetzungen

RELion / Business Central

Automatische Secret-Erneuerung ist nur möglich, wenn:

Diese Voraussetzungen werden von RELion automatisch geprüft (siehe Abschnitt Einrichtung in RELion).

Microsoft Entra ID

Das ist der wichtigste und am häufigsten übersehene Einrichtungsschritt. Ohne die folgende Konfiguration schlägt jede automatische Erneuerung mit einem Berechtigungsfehler (Authorization_RequestDenied / “Insufficient privileges to complete the operation”) fehl — der Connector selbst funktioniert davon unabhängig weiter, nur die automatische Erneuerung nicht.

Grund: RELion muss sich gegenüber Microsoft Graph als die Entra-Anwendung selbst ausweisen und sich selbst ein neues Secret hinzufügen dürfen. Dafür reicht die reine Zustimmung zu einer API-Berechtigung nicht aus — die Anwendung muss zusätzlich formal als Besitzer (Owner) ihres eigenen Anwendungsobjekts eingetragen sein.

Schritt 1 — API-Berechtigung hinzufügen: In der Entra-App-Registrierung (dieselbe Anwendung, die im RELion-Setup-Wizard als Entra Application hinterlegt ist) → API permissions → Add a permission → Microsoft Graph → Application permissions (nicht Delegated) → Application.ReadWrite.OwnedBy hinzufügen.

Schritt 2 — Admin Consent erteilen: Auf derselben Seite Grant admin consent for <Tenant> anklicken. Ohne diesen Schritt bleibt die Berechtigung wirkungslos.

Schritt 3 — Die Anwendung als Besitzer ihrer selbst eintragen: Dieser Schritt lässt sich nicht über die normale Azure-Portal-Oberfläche ausführen (dort können unter “Owners” nur Benutzer, keine Dienstprinzipale hinzugefügt werden). Er erfordert Azure CLI, PowerShell oder den Graph Explorer:

az login
$spId = az ad sp show --id <ClientId> --query id -o tsv          # Objekt-ID des Dienstprinzipals (Enterprise Application)
$appObjectId = az ad app show --id <ClientId> --query id -o tsv  # Objekt-ID der App-Registrierung
az ad app owner add --id $appObjectId --owner-object-id $spId

<ClientId> ist die Client-ID der Entra-Anwendung (im RELion-Datensatz AAD Application hinterlegt).

Alternative zu Schritt 3: Statt Application.ReadWrite.OwnedBy kann auch direkt Application.ReadWrite.All (ebenfalls Application permission, mit Admin Consent) vergeben werden. Dann entfällt die Besitzer-Zuweisung, dafür hat die Anwendung Schreibzugriff auf alle App-Registrierungen im Tenant — für produktive Umgebungen aus Sicherheitssicht in der Regel die schlechtere Wahl, aber als schnellere Übergangslösung nutzbar.

Benötigte Rolle: Wer diese drei Schritte ausführt, benötigt eine der folgenden Microsoft Entra-Rollen: Global Administrator, Privileged Role Administrator, Cloud Application Administrator oder Application Administrator.

Einrichtung in RELion

Es gibt zwei Wege, wie die automatische Secret-Erneuerung aktiviert wird:

A — Neue Installation

Beim erstmaligen Durchlaufen des Setup-Assistenten Get started with RELion Archiv Kompakt Connector wird die Erneuerung automatisch mit aktiviert, sofern die Verbindung im Cloud-Modus eingerichtet wird: Beim Abschluss (Finish) werden die täglichen Aufgabenwarteschlangenposten automatisch angelegt, und es wird sofort ein erster Prüflauf angestoßen, damit das Ablaufdatum des Secrets direkt sichtbar ist.

Schlägt dieser Sofort-Check fehl (z. B. weil die Entra-Voraussetzungen nicht erfüllt sind), wird das lediglich protokolliert — der Setup-Assistent wird davon nicht beeinträchtigt und kann normal abgeschlossen werden. Die tägliche Prüfung läuft danach trotzdem regulär weiter und versucht es erneut.

B — Bestandskunden (Connector bereits eingerichtet)

Kunden, die den Connector-Setup-Assistenten bereits vor Einführung dieses Features abgeschlossen haben, müssen die Secret-Erneuerung nachträglich aktivieren – dafür gibt es einen eigenen, zweiten Assisted-Setup-Eintrag:

Set up automatic Secret Renewal for Archiv Kompakt (in derselben Assisted-Setup-Gruppe wie der ursprüngliche Connector-Setup-Assistent).

Beim Öffnen dieses Assistenten prüft RELion automatisch die RELion/Business Central-Voraussetzung:

• Sind alle Voraussetzungen erfüllt, zeigt die Seite eine Bestätigung an, und der Finish-Button ist aktiv. Ein Klick darauf registriert die tägliche Aufgabenwarteschlangenposition und markiert den Assistenten als abgeschlossen.
• Fehlt etwas, zeigt die Seite den konkreten Grund an (z. B. “Cloud-Modus nicht aktiv” oder “Microsoft Entra Application fehlt”) und bietet einen direkten Link zum ursprünglichen Connector-Setup-Assistenten an, um die fehlende Konfiguration zu ergänzen. Finish bleibt so lange deaktiviert.

Die Seite weist außerdem direkt auf die Entra-Voraussetzungen hin, bevor der Administrator fortfährt.

Täglicher Prüfablauf

Sind Voraussetzungen erfüllt und die tägliche Aufgabe eingerichtet, läuft folgender Ablauf einmal pro Tag automatisch ab:

1. RELion holt sich über das aktuell hinterlegte Secret ein Zugriffstoken für Microsoft Graph.
2. RELion fragt bei Microsoft Graph das aktuelle Ablaufdatum des Secrets ab und speichert es am Entra-Anwendungsdatensatz in RELion.
3. Läuft das Secret nicht innerhalb der nächsten 21 Tage ab, ist der Vorgang für diesen Tag beendet.
4. Läuft es innerhalb der nächsten 21 Tage ab:
   • Ein neues Secret wird über Microsoft Graph erzeugt.
   • Das neue Secret wird an Archiv Kompakt übertragen.
   • Erst wenn Archiv Kompakt das neue Secret bestätigt hat, übernimmt RELion es intern und speichert das neue Ablaufdatum.
5. Bei jedem Fehlschlag in diesem Ablauf bleibt das bisherige, noch gültige Secret unverändert in Kraft — es wird nichts verworfen oder überschrieben, bevor der Ersatz nicht sicher an beiden Stellen (Entra ID und Archiv Kompakt) vorhanden ist. Der nächste tägliche Lauf versucht es automatisch erneut.

Benachrichtigungen

• Erfolg: Nach erfolgreicher Erneuerung erhält der Benutzer eine Benachrichtigung mit dem neuen Ablaufdatum.
• Fehlschlag: Bei einem Fehler erscheint eine Benachrichtigung mit der Fehlerursache und einer Aktion Open Entra Application, die direkt zur betroffenen Entra-Anwendungskarte führt.
  • Fehlt speziell die in Abschnitt 2 beschriebene Berechtigung/Besitzer-Zuweisung, erkennt RELion das automatisch und zeigt statt der technischen Rohfehlermeldung eine verständliche, handlungsleitende Meldung mit den konkret fehlenden Schritten an.
  • Jeder Fehlschlag wird zusätzlich in der Telemetrie protokolliert.

Einschränkung beim manuellen Testen

Wird die tägliche Aufgabenwarteschlangenposition manuell über die Business-Central-Funktion Aufgabenwarteschlangenposten ausführen angestoßen (statt sie regulär nach Zeitplan laufen zu lassen), kann dies zu einer technischen Fehlermeldung führen (“Aufrufen der Funktion ‘MODIFY’ … nicht zulässig, wenn es als TryFunction verwendet wird”). Das ist eine Eigenheit dieser manuellen Testfunktion in Business Central und keine Fehlfunktion des Features — der reguläre, geplante Lauf ist davon nicht betroffen. Zum gezielten Testen empfiehlt sich stattdessen, den regulären Zeitplan abzuwarten oder den Connector-Setup-Assistenten erneut über Finish abzuschließen.

Zusammenfassung für Administratoren

Die folgende Checkliste ist hilfreich für die Prüfung: