# Initiale App-Registrierung in Microsoft Azure

Damit ELO Azure Administration die Verbindung zu Microsoft Azure aufbauen kann, müssen Sie eine erste App-Registrierung über Microsoft Azure vornehmen.

Beachten Sie

Die grundlegende Einrichtung einer Microsoft-Azure-Umgebung sowie der Abschluss entsprechender Abonnements werden an dieser Stelle vorausgesetzt und sind nicht Teil dieser Dokumentation.

# App registrieren

Melden Sie sich als mit administrativen Rechten in Microsoft Azure an.
Öffnen Sie den Bereich App-Registrierungen.
Wählen Sie Neue Registrierung.

Die Seite Anwendung registrieren erscheint.
Tragen Sie einen Namen für die App ein. Sie können diesen frei wählen.

Beispiel: ELO Azure Administration
Wählen Sie bei Unterstützte Kontotypen die Option Nur ein Mandant aus.
Wählen Sie bei Umleitungs-URI die Plattform Web und tragen Sie einen Wert nach diesem Schema ein: https://<Server>:<Port>/signin-oidc-custom.

Beispiel: https://win-fja1f4blafg:9033/signin-oidc-custom

Information

Der Pfad /signin-oidc-custom kann in der Datei appsettings.json geändert werden. Weitere Informationen dazu finden Sie im Kapitel Konfiguration des Dienstes > AzureAd.
Wählen Sie Registrieren.

Die App wird in Microsoft Azure registriert.

# Anmeldungseinstellungen

Nachdem die Registrierung abgeschlossen ist, müssen Sie einige Einstellungen für die Anmeldung der App konfigurieren.

Öffnen Sie in Microsoft Azure den Bereich Authentifizierung.
Wählen Sie Einstellungen.
Aktivieren Sie unter Web- und SPA-Einstellungen > Implizite Genehmigung und Hybridflows folgende Optionen:
- Zugriffstoken (werden für implizite Flows verwendet)
- ID-Token (werden für implizite und Hybridflows verwendet)
Speichern Sie die Einstellungen.

Die Anmeldungseinstellungen sind nun konfiguriert.

# Geheimer Clientschlüssel (Secret)

Damit die Verbindung zur Microsoft-Azure-App funktioniert, benötigt diese noch einen geheimen Clientschlüssel (Secret). Dieser muss in der Datei appsettings.json eingetragen werden.

Achtung

Erneuern Sie regelmäßig den geheimen Clientschlüssel, bevor seine Gültigkeitsdauer abläuft.

Öffnen Sie in Microsoft Azure den Bereich Zertifikate & Geheimnisse.
Wählen Sie Neuer geheimer Clientschlüssel.

Der Bereich Geheimen Clientschlüssel hinzufügen erscheint.
Tragen Sie in das Feld Beschreibung eine kurze Beschreibung für den geheimen Clientschlüssel ein.
Wählen Sie bei Gültig bis einen Zeitraum aus.
Bestätigen Sie mit Hinzufügen.

Microsoft Azure erstellt einen geheimen Clientschlüssel.
Kopieren Sie den Clientschlüssel aus der Spalte Wert.

Beachten Sie

Notieren Sie sich den Wert des geheimen Clientschlüssels unmittelbar nach dem Erstellen. Dieser Wert wird nicht mehr vollständig angezeigt, wenn Sie die Übersicht der Geheimnisse zu einem späteren Zeitpunkt erneut aufrufen.
Fügen Sie den kopierten Clientschlüssel in der Datei appsettings.json ein.

# API-Berechtigungen

Die App für ELO Azure Administration benötigt einige Berechtigungen.

Öffnen Sie den Bereich API-Berechtigungen.
Wählen Sie Berechtigungen hinzufügen.

Der Bereich API-Berechtigungen anfordern erscheint.
Fügen Sie folgende delegierten Berechtigungen hinzu:
- Azure Service Management:
  - user_impersonation
- Microsoft Graph:
  - Application.ReadWrite.All
  - AppRoleAssignment.ReadWrite.All
  - Directory.ReadWrite.All
  - offline_access
  - openid
  - profile
  - RoleManagement.ReadWrite.Directory
  - User.Read
  - User.ReadWrite.All
Wählen Sie Administratorzustimmung für <Mandant> erteilen.

Der Abfrage-Dialog Bestätigung der Administratoreinwilligung erscheint.
Bestätigen Sie mit Ja.

Die Berechtigungen werden hinzugefügt.

# Authentifizierung über ELO Modern Authentication (Auth2) konfigurieren

Damit ELO Azure Administration sich am ELO System authentifizieren kann, müssen Sie die App in ELO Modern Authentication (Auth2) als neuen OpenID-Anbieter hinzufügen.

Öffnen Sie in der ELO Administration Console den Bereich Anmeldekonfiguration.
Wählen Sie OpenID-Anbieter hinzufügen....

Ein Drop-down-Menü erscheint.
Wählen Sie Microsoft.
Tragen Sie einen Namen für die ID ein, z. B. elo_az_oauth.

Dieser Wert ist später erforderlich für die Konfigurationsdatei appsettings.json (Wert EloOAuth).
Kopieren Sie in der Microsoft-Azure-App den Wert bei Anwendungs-ID (Client).
Fügen Sie den Wert auf der Konfigurationsseite von ELO Modern Authentication unter Client-ID ein.
Kopieren Sie aus Microsoft Azure den Wert bei Verzeichnis-ID (Mandant).
Fügen Sie den Wert auf der Konfigurationsseite von ELO Modern Authentication unter Issuer an Stelle des Platzhalters {tenant} ein.
Fügen Sie unter Client-Secret den Wert des geheimen Clientschlüssels ein.
Fügen Sie unter Audience die GUID für Microsoft Graph 00000003-0000-0000-c000-000000000000 oder die URL https://graph.microsoft.com ein.

Optional: Aktivieren Sie die Option Versteckt, damit dieser OpenID-Anbieter nicht in ELO Anmeldedialogen erscheint.
Wählen Sie Speichern.

Der neue OpenID-Anbieter für ELO Azure Administration wird erstellt.

Für die Verbindung müssen Sie in Microsoft Azure die Callback-URL für die entsprechende App hinterlegen.
Kopieren Sie die Callback-URL.
Öffnen Sie in Microsoft Azure die App für ELO Azure Administration.
Wechseln Sie in den Bereich Authentication (Preview).
Wählen Sie Umleitungs-URI hinzufügen > Web.
Fügen Sie die Callback-URL ein.
Wählen Sie Konfigurieren.

Die Authentifizierung über ELO Modern Authentication ist konfiguriert.

Sie können die Konfiguration in ELO Modern Authentication über Anbindung testen überprüfen.

# Dienst 'ELO Azure Administration' konfigurieren

Nachdem die App in Azure eingerichtet wurde, müssen Sie die Konfiguration des Dienstes ELO Azure Administration im ELO System anpassen.

Im Folgenden ist eine grundlegende Konfiguration über die Konfigurationsdatei appsettings.json beschrieben. Im Standard sind einige Werte vorausgefüllt.

Information

Weitere Konfigurationsmöglichkeiten finden Sie im Kapitel Konfiguration des Dienstes.

Öffnen Sie in Microsoft Azure die Übersicht der zuvor erstellten App.
Kopieren Sie die Werte folgender Felder:
- Anwendungs-ID (Client)
- Verzeichnis-ID (Mandant)
Öffnen Sie auf der Server-Maschine, auf der ELO läuft, folgendes Verzeichnis:

<ELO>\servers\ELO-Azure-Administration

Information

Der Platzhalter <ELO> steht für das ELO Installationsverzeichnis.
Kopieren Sie die Datei appsettings.json und speichern Sie die Kopie als appsettings.Production.json im selben Ordner.

Bei Updates wird appsettings.Production.json nicht überschrieben. Das stellt sicher, dass Ihre Konfiguration erhalten bleibt.

Öffnen Sie die Datei appsettings.json in einem geeigneten Editor.

Im Kopfbereich der Datei finden Sie folgende Einträge:

  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "",
    "ClientId": "",
    "TenantId": "",
    "ClientSecret": "",
    "CallbackPath": "/signin-oidc-custom"
  },

Fügen Sie die kopierten Werte sowie den geheimen Clientschlüssel in die JSON-Datei ein.

Schema:

  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "Domain": "<Domain-Name>.onmicrosoft.com",
    "ClientId": "<Anwendungs-ID>",
    "TenantId": "<Verzeichnis-ID>",
    "ClientSecret": "<Wert des geheimen Clientschlüssels>",
    "CallbackPath": "/signin-oidc-custom"
  },

Passen Sie bei Bedarf den Eintrag EnableRepositoryConfigPolling an.

Im Standard ist der Wert des Eintrags EnableRepositoryConfigPolling auf true gesetzt. Dadurch werden möglicherweise lokal vorhandene Einstellungen durch Einstellungen aus dem Repository ersetzt.

Alternativ: Setzen Sie den Wert auf false, wenn ELO Azure Administration von einer anderen als der internen Domäne aufgerufen werden soll, z.B. über einen Proxy. Kopieren Sie den Wert für PublicUrl aus dem Repository und tragen ihn hier ein.

Beispiel:
```
"PublicUrl": "https://<Server>:<Port>/Path/to/ELOAzureAdministration",
```
Weitere Informationen dazu finden Sie im Kapitel Konfiguration des Dienstes > EnableRepositoryConfigPolling.
Ändern Sie die Anmeldedaten für das Konto ELO Service, der für die Verbindung zum ELO Repository verwendet werden soll.
```
"ServiceUser": {
 "UserName": "ELO Service",
 "Password": "<Passwort für das Service-Konto>"
}
```

Konfigurieren Sie die ELO Repositorys, die über die ELO Azure Administration zugänglich sein sollen. Ergänzen Sie für die Authentifizierung die Einstellung "loginmode": "auth2".

Schema:

  "Repositories": [
    {
      "name": "<Anzeigename des Repositorys>",
      "key": "<Technischer Schlüssel des Repositorys>",
      "url": "https://<Server>:<Port>/ix-<Repository>/ix",
      "webclienturl": "https://<Server>:<Port>/ix-<Repository>/plugin/de.elo.ix.plugin.proxy/web/",
      "oauthcallbackurl": "https://<Server>:<Port>/ix-<Repository>/",
      "loginmode": "auth2"
    }
  ],

Information

Der technische Schlüssel für das Repository kann ein beliebiges Zeichen außer einem Leerzeichen sein. Es wird empfohlen, den Repository-Namen zu verwenden, es sei denn, dieser Name ist nicht auf allen Servern eindeutig.

Ändern Sie ggf. den Wert für die Eigenschaft ConfigId. Dieser wird verwendet, wenn sich ein Benutzer in der Web-Oberfläche von ELO Azure Administration anmeldet.

Tragen Sie als Wert die ID des für die Anmeldung konfigurierten OpenID-Anbieters aus ELO Modern Authentication ein.
```
"EloOAuth": {
  "ConfigId": "elo_az_oauth"
},
```
Geben Sie unter Database und ConnectionStrings den Datenbanktyp und den Connection String ein.

Konfigurieren Sie unter Kestrel die Endpunkte des Webservers.

Windows:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://elo-azadmin-server",
      "Certificate": {
        "Path": "C:\\Path\\To\\Certificate.pfx",
        "Password": "<Passwort für Zertifikat>"
      }
    }
  },
},

Linux:

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://elo-azadmin-server",
      "Certificate": {
        "Path": "/path/to/certificate.pem",
        "Password": "<Passwort für Zertifikat>"
      }
    }
  },
},

Speichern Sie die Datei.
Starten Sie den Dienst ELO Azure Administration neu.

Die Konfiguration des Dienstes ist abgeschlossen. Sie können sich nun über ELO Azure Administration in Microsoft Azure anmelden.

Um ELO Azure Administration zu testen, öffnen Sie ein Terminal im Installationsverzeichnis von ELO Azure Administration und führen Sie den folgenden Befehl aus:

Windows: .\Elo.Azure.Administration.Main.exe
Linux: ./Elo.Azure.Administration.Main

# Service-Registrierung

Nachdem ELO Azure Administration installiert wurde, können Sie es optional als Systemdienst registrieren, sodass es beim Starten des Betriebssystems automatisch mit gestartet wird.

# Windows

Um ELO Azure Administration als Windows-Dienst zu registrieren, führen Sie den folgenden Befehl in einer administrativen PowerShell aus:

New-Service -Name ELOAzAdmin -DisplayName "ELO Azure Administration" -Description "ELO Azure Administration provides synchronization between ELO repositories and third-party systems" -BinaryPathName C:\Full\Path\To\ELOAzAdmin\Elo.Azure.Administration.Main.exe

Information

Mit diesem Befehl wird der ELO Azure Administration-Dienst unter dem SYSTEM-Konto der Windows-Installation ausgeführt.

# Linux

Erstellen Sie eine systemd-Unit-Datei ELOAzAdmin.service für den elo-azadmin-Dienst mit folgendem Inhalt:

[Unit]
Description=ELO Azure Administration provides synchronization between ELO
repositories and third-party systems
[Service]
WorkingDirectory=/path/to/ELOAzAdmin/
ExecStart=/path/to/ELOAzAdmin/Elo.Azure.Administration.Main
# Always restart if the service exits
Restart=always
RestartSec=5
KillSignal=SIGINT
Environment=ASPNETCORE_ENVIRONMENT=Production

Beachten Sie

Mit diesen Anweisungen wird der ELO Azure Administration-Dienst als root ausgeführt.

Dies wird nicht empfohlen, die Einrichtung eines Service-Benutzerkontos und dessen Konfiguration werden jedoch nicht dieser Dokumentation beschrieben. Wie Sie dies erreichen können, lesen Sie in der Dokumentation Ihrer Linux-Distribution.

Öffnen Sie ein Terminal in dem Verzeichnis, in dem Sie die Datei ELOAzAdmin.service erstellt haben, und führen Sie die folgenden Befehle aus:

sudo cp ELOAzAdmin.service /etc/systemd/system/ELOAzAdmin.service
sudo systemctl daemon-reload
sudo systemctl start ELOAzAdmin.service
# If you want to enable auto start execute the following
sudo systemctl enable ELOAzAdmin.service

← Voraussetzungen Konfiguration des Dienstes →