# 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.

# 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. Sie können dies entweder über die Konfigurationsdatei appsettings.json oder über das ELO Repository tun.

Im Folgenden ist eine grundlegende Konfiguration beschrieben.

Ö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.

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 Profile Key für das ELOauth Plug-in. Dieser wird verwendet, wenn sich ein Benutzer in der Web-Oberfläche von ELO Azure Administration anmeldet.
```
"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.

Information

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

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, müssen Sie den folgenden Befehl in einer administrativen PowerShell ausführen:

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

Information

Mit diesen Anweisungen wird der ELO Azure Administration-Dienst dann als root ausgeführt. Dies wird nicht empfohlen, aber die Einrichtung eines Service-Benutzerkontos und dessen Konfiguration liegt jedoch außerhalb des Rahmens dieser Anleitung. Bitte schauen Sie in der Dokumentation Ihrer Linux-Distribution nach, wie Sie dies erreichen können.

Öffnen Sie ein Terminal in dem Verzeichnis, in dem Sie die Datei ELOAzAdmin.service erstellt haben, und führen Sie dann 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 →