Wechsel zur verwalteten RealmJoin-App

Ersetzen Sie die mandantenbezogene App-Registrierung der RealmJoin Runbook Management-App und deren Client-Geheimnis durch die verwaltete mandantenübergreifende RealmJoin-App, indem Sie das RealmJoin-PowerShell-Modul verwenden.

Übersicht

Tenants, die Azure Automation vor dem PowerShell-basierten Onboarding verbunden haben, verwenden eine RealmJoin Runbook Management App-Registrierung in ihrem eigenen Tenant. RealmJoin authentifiziert sich gegenüber Ihrem Automation Account mit der Client-ID und dem Client-Secret dieser App.

Neu eingebundene Tenants tun das nicht mehr: RealmJoin verwendet sein eigenes Multi-Tenant-Anwendung, die auf Ihrem Automation Account nur Contributor zugewiesen bekommt und sonst nichts. Sie können eine vorhandene Konfiguration mit dem RealmJoin PowerShell module.

Hier gibt es keine Frist. Anders als bei der Log-Analytics-Migration, wird von Microsoft nichts außer Betrieb genommen — der Legacy-Pfad funktioniert weiter. Wechseln Sie, wann es Ihnen passt.

Warum wechseln

• Kein Client-Secret, das rotiert werden muss. Das mandantenspezifische Secret läuft ab und muss erneuert werden; wenn es abläuft, stoppen Runbook-Synchronisierung und Runbook-Ausführung, bis es jemand bemerkt. Die verwaltete App hat auf Ihrer Seite kein Secret.
• Keine App-Registrierung, die gepflegt werden muss in Ihrem Tenant.
• Engerer Umfang. Dem Legacy-Service-Principal wurde typischerweise Contributor für die gesamte Ressourcengruppe zugewiesen. Der verwalteten App wird nur auf dem Automation Account Contributor zugewiesen.
• Ihr Automation Account, seine verwaltete Identität, seine Berechtigungen und Ihre Runbooks bleiben alle genau so, wie sie sind.

Was der Wechsel ändert

Dasselbe Set-RJAutomationAccount Befehl wie bei einer neuen Einrichtung wird verwendet, bezogen auf Ihren vorhandenes Automation Account. Er:

• erstellt den RealmJoin Azure Resources Service Principal in Ihrem Tenant, falls er noch nicht vorhanden ist
• weist ihm Contributor auf diesem Automation Account zu
• setzt die Anwendungsberechtigungen der verwalteten Identität — Microsoft Graph, Exchange Online, Defender und SharePoint — für den vom Modul gebündelten Satz erneut durch
• teilt RealmJoin mit, sich ab jetzt mit der verwalteten App zu authentifizieren

Ihr Automation Account behält seinen Namen, seine verwaltete Identität und seine Objekt-ID, sodass die Entra ID-Rollen und alle Berechtigungen, die Sie ihm zugewiesen haben, gültig bleiben. Runbooks werden nicht von Grund auf neu importiert.

Die Registrierung setzt den konfigurierten Branch des gemeinsamen Runbook-Repositorys auf production. Wenn Ihr Tenant absichtlich einem anderen Branch folgt, setzen Sie ihn anschließend im Portal unter Settings → Runbooks erneut.

Voraussetzungen

Dasselbe wie für eine neue Einrichtung — siehe Voraussetzungen auf der Onboarding-Seite. Kurz gesagt:

• Zugriff auf den Bereich Settings im RealmJoin Portal, um den Befehl und sein Token zu erhalten
• PowerShell 5.1 oder höher, in einer frisch geöffneten lokalen Sitzung — nicht Azure Cloud Shell
• Ein Konto, das Service Principals erstellen und Anwendungsberechtigungen in Entra ID gewähren kann (Global Administrator oder Privileged Role Administrator) und Rollenzuweisungen im Abonnement erstellen kann (Owner oder Contributor sowie User Access Administrator)

Migration

1

Den Befehl aus dem RealmJoin Portal kopieren

Gehen Sie im RealmJoin Portal zu Einstellungen → Runbooks (https://portal.realmjoin.com/settings/runbooks-configuration).

Die Seite zeigt den Hinweis "Wechseln Sie zur verwalteten RealmJoin-App" zusammen mit einem fertigen Befehlsblock zum Kopieren. Verwenden Sie den Kopieren zum Kopieren.

Der Befehl ist bereits mit Ihrer aktuellen Ressourcengruppe, dem Namen des Automation Account und dem Abonnement vorausgefüllt:

$latest = [version](Find-Module RealmJoin -Repository PSGallery -ErrorAction Stop).Version
if (-not (Get-Module -ListAvailable RealmJoin | Where-Object Version -ge $latest)) {
    Install-Module RealmJoin -Force -AllowClobber -ErrorAction Stop
}
Import-Module RealmJoin -Force
Set-RJAutomationAccount -ResourceGroupName "<ResourceGroup>" -AutomationAccountName "<AutomationAccountName>" -SubscriptionId "<SubscriptionId>" -Token "<Token>" 6>&1

Stellen Sie sicher -AutomationAccountName ist vorhanden und benennt Ihren vorhandenes Konto. Ohne ihn erstellt das Modul einen neuen, leeren Automation Account, anstatt den von Ihnen verwendeten zu wechseln.

2

Führen Sie den Befehl aus

Fügen Sie den Block in eine neue PowerShell-Sitzung ein und führen Sie ihn aus. Das Token ist ungefähr eine Stunde lang gültig — wenn es abgelaufen ist, laden Sie die Einstellungsseite neu und kopieren Sie den Befehl erneut.

Sie werden aufgefordert, sich anzumelden mit Connect-AzAccount. Die Bereitstellung meldet dann jede Ressource und jede Rollenzuweisung, sobald sie angewendet wird; alles, was bereits existiert, wird erkannt und übersprungen.

Abmelden danach: Die Azure-Anmeldung bleibt nach dem Ende des Befehls aktiv. Wenn Sie fertig sind, führen Sie Disconnect-AzAccount aus, um sich von der vorhandenen Sitzung abzumelden.

3

Überprüfen Sie im Portal

Kehren Sie zurück zu Einstellungen → Runbooks und wählen Sie Aktualisieren.

Der Migrationshinweis ist verschwunden, und die Seite zeigt jetzt Runbook-Synchronisierungseinstellungen mit den Branch- und Hybrid Runbook Worker-Optionen sowie einem schreibgeschützten Azure connection Abschnitt. Client ID und Client Secret sind nicht mehr Teil der Konfiguration.

Prüfen Sie, ob der Branch der gewünschte ist, und führen Sie dann ein Runbook aus, um zu bestätigen, dass die Ausführung weiterhin funktioniert.

4

Bereinigen Sie die alte App-Registrierung

Sobald alles funktioniert, kann die RealmJoin Runbook Management App-Registrierung wird für Runbooks nicht mehr verwendet und kann in Entra ID zusammen mit ihrer Contributor-Rollenzuweisung auf die Ressourcengruppe entfernt werden.

Prüfen Sie zuerst, was diese App-Registrierung sonst noch verwendet. Es ist dieselbe App, die die legacy Log Analytics Einrichtung möglicherweise wiederverwendet — wenn Ihr Tenant dort noch die Data Collector API verwendet oder weiterhin Protokolldaten liest, die vor dieser Migration geschrieben wurden, werden die App-Registrierung und ihr Secret weiterhin benötigt. Siehe Migration zur Log Ingestion API.

Problembehandlung

"RealmJoin-Modul ist veraltet - Ausführung kann nicht fortgesetzt werden"

Jedes Cmdlet prüft einmal pro Sitzung, ob Sie die neueste veröffentlichte Version verwenden. Installieren Sie die aktuelle Version, schließen Sie dann die Sitzung und öffnen Sie eine neue:

Install-Module -Name RealmJoin -Force -Scope CurrentUser

Ein Konflikt bei der Modullversion wird gemeldet

Ein Az.* Ein Modul in einer anderen Version als der, die das RealmJoin-Modul fest vorgibt, ist bereits in der Sitzung geladen. Dies kann nicht in der laufenden Sitzung behoben werden — schließen Sie PowerShell, öffnen Sie eine neue Sitzung und führen Sie den Befehl erneut aus. Das ist auch der Grund, Azure Cloud Shell nicht zu verwenden.

Die Bereitstellung schlägt fehl, während Rollenzuweisungen erstellt werden

Das Erstellen der Contributor-Zuweisung auf dem Automation Account erfordert eine Rolle, die Zugriffe verwalten kann — zum Beispiel Owner, User Access Administrator oder Role Based Access Control Administrator. Contributor allein nicht aus.

Bereits vorhandene Rollenzuweisungen werden erkannt und übersprungen, daher ist es sicher, den Befehl nach der Behebung der Berechtigungen erneut auszuführen.

Die Bereitstellung schlägt fehl, während Anwendungsberechtigungen zugewiesen werden

Das Gewähren von Graph-, Exchange-, Defender- und SharePoint-App-Rollen an die verwaltete Identität erfordert Global Administrator oder Privileged Role Administrator. Lassen Sie den Befehl von jemandem mit dieser Rolle ausführen, oder führen Sie ihn selbst erneut aus, nachdem die Rolle aktiviert wurde.

Die Runbook-Synchronisierung funktioniert nach dem Wechsel nicht mehr

Öffnen Sie Einstellungen → Runbooks und prüfen Sie die oben auf der Seite angezeigte Warnung — RealmJoin überprüft die Automation Account-Konfiguration jedes Mal, wenn die Seite geladen wird. Verwenden Sie dann Cmdlet anzeigen unter Azure-Verbindung, um den Einrichtungsbefehl erneut auszuführen; er ist idempotent und wendet alles, was fehlt, erneut an.