Microsoft Entra ID/Azure AD anbinden

Microsoft Entra ID, früher Azure Active Directory, ist ein Cloud-basierter Dienst für das Identitäts- und Zugriffsmanagement von Anwendungen, die in Microsoft Azure gehostet werden, sowie von Anwendungen, die in anderen Clouds oder On-Premise-Umgebungen ausgeführt werden. Entra ID bietet Funktionen wie Single Sign-On, Multi-Faktor-Authentifizierung, Self-Service Password Reset, Conditional Access Policies und Identitätsschutz. Mit Entra ID können Organisationen ihre Benutzer, Gruppen und Geräte zentral verwalten und den Zugriff auf ihre Ressourcen steuern.

Das Web Management des OPC Router 5 ermöglicht die Benutzerverwaltung und Authentifizierung über Entra ID, indem Entra ID angebunden wird.

Eine allgemeine Einführung in die zugrunde liegenden OAuth-2-Begriffe (Client ID, Tenant ID, Redirect URI, Scopes) finden Sie unter OAuth 2.0 – Grundlagen.

hinweis

Für diese Anleitung wird ein bestehender Microsoft Entra ID Tenant vorausgesetzt.

Damit der OPC Router Entra ID verwenden kann, muss eine neue Registrierung zu den Anwendungsregistrierungen Ihres Microsoft Entra ID Tenants hinzugefügt werden.

Auf der Registerkarte App-Registrierungen (1) Ihres Microsoft Entra ID Tenants können Sie eine neue Anwendung erstellen, indem Sie auf Neue Registrierung (2) klicken.

Es ist wichtig, dass die Umleitungs-URI der Anwendung angepasst wird. In der Auswahlliste (1) muss Web ausgewählt werden. Als Adresse (3) muss die Adresse konfiguriert werden, unter der das Web Management erreichbar ist. Dies muss die gültige https (2) Adresse des Web Managements sein, ansonsten ist dies nicht erlaubt. Das SSL-Zertifikat muss nicht von einer Zertifizierungsstelle ausgestellt sein, auch selbstsignierte Zertifikate sind zulässig. Wie Sie Https für Ihre OPC Router Web Management einrichten, erfahren Sie hier:

HTTPS verwenden

Als Endpunkt (4) muss zusätzlich der eingestellte Login-Request-Pfad übergeben werden. Dieser ist standardmäßig /signin-oidc, kann aber auch bei Bedarf durch die Umgebungsvariable AZURE_AD_CALLBACK_PATH überschrieben werden.

Die neu erstellte Anwendung muss noch konfiguriert werden, damit die Authentifizierung über Microsoft Entra ID erfolgreich durchgeführt werden kann.

Wählen Sie dazu in der Registerkarte App-Registrierungen (1) unter der Gruppe Alle Anwendungen (2) Ihre soeben erstellte Anwendung (3) aus.

Auf der Registerkarte Authentifizierung (1) befindet sich das Kontrollkästchen ID-Token (2), das aktiviert sein muss, damit die Benutzerverwaltung des Web Management über Microsoft Entra ID funktioniert. Speichern (3) Sie diese Einstellungsänderung.

In Ihrem Entra ID Tenant können Sie nun über die Registerkarte Unternehmensanwendungen zu Ihrer jetzt konfigurierten Anwendung navigieren und die Registerkarte Benutzer und Gruppen für die Benutzerverwaltung verwenden.

OPC Router 5 Container mit Anbindung an Entra ID erstellen

Damit der OPC Router mit Entra ID verbunden werden kann, müssen drei Informationen vom Tenant verfügbar sein: Die Anwendungs-ID, die Verzeichnis-ID und eine Domäne, unter der die Entra ID Konfiguration erreichbar ist.

Die Primäre Domäne (3) finden Sie im der Registerkarte Übersicht (1) unter dem Tab Übersicht (2) Ihres Entra ID Tenants.

Die Anwendungs-ID (2) und die Verzeichnis-ID (3) werden auf der Registerkarte Übersicht (1) der erstellten Anwendungsregistrierung angezeigt.

Mit diesen Informationen können Sie nun einen Docker-Run-Befehl ausführen, der einen OPC Router Container mit einer Verbindung zu Entra ID erstellt:

docker run -d \
    -e OR_I_ACCEPT_EULA=true \
    -e AZURE_AD_DOMAIN=domain.onmicrosoft.com \
    -e AZURE_AD_TENANT_ID=1111111-1111-1111-1111-1111111 \
    -e AZURE_AD_CLIENT_ID=1111111-1111-1111-1111-1111111 \
    -v $PWD/https.pem:/inray/https.pem \
    -v $PWD/https.key:/inray/https.key \
    -e OR_WEB_HTTPS_CERTIFICATE_PEM_FILE=/inray/https.pem \
    -e OR_WEB_HTTPS_CERTIFICATE_KEY_PEM_FILE=/inray/https.key \
    -e OR_WEB_DISABLE_HTTPS=false \
    -p 443:8443 \
    --name opcrouterentra \
    opcrouter/runtime

hinweis

Mit Ausführen des Befehls stimmen Sie durch dem Setzen der Umgebungsvariable OR_I_ACCEPT_EULA auf true den Endbenutzer-Lizenzbedingungen zu.

Geben Sie Ihre (primäre) Domäne in die Umgebungsvariable AZURE_AD_DOMAIN, Ihre Verzeichnis-ID in die Umgebungsvariable AZURE_AD_TENANT_ID und Ihre Anwendungs-ID in die Umgebungsvariable AZURE_AD_CLIENT_ID ein.

Optional können Sie Nutzer bereits beim Start des Containers über OR_EXTERNAL_USER_ADMIN_EMAILS, OR_EXTERNAL_USER_EDITOR_EMAILS und OR_EXTERNAL_USER_OBSERVER_EMAILS als externe Nutzer vorprovisionieren. Diese erscheinen in der Benutzerverwaltung mit dem Kennzeichen External und benötigen kein lokales Passwort.

Wenn AZURE_AD_DISABLE_AUTO_PROVISION=true gesetzt ist, können sich ausschließlich solche bereits vorhandenen externen Nutzer anmelden. Neue Entra-ID-Nutzer werden dann beim ersten Login nicht mehr automatisch angelegt.

Wenn AZURE_AD_DISABLE_AUTO_PROVISION nicht gesetzt ist oder auf false steht, werden Nutzer beim Entra-ID-Login weiterhin automatisch angelegt oder aktualisiert. Die Rollen werden dabei bei jedem Login aus den übertragenen Rollen-Claims synchronisiert.

warnung

Ohne Rollen-Claim wird jeder Anmelder zum Administrator. Liegen beim Login keine Rollen-Claims vor, setzt der OPC Router derzeit automatisch die lokale Rolle Admin. Solange die Anwendungsregistrierung keine App-Rollen zuweist, erhält damit jeder Nutzer des Tenants, der sich anmelden kann, volle Rechte im OPC Router.

Dagegen hilft eines von beidem:

• Legen Sie die App-Rollen an und weisen Sie jedem Nutzer eine Rolle zu – siehe Nutzerrollen per Entra ID.
• Setzen Sie AZURE_AD_DISABLE_AUTO_PROVISION=true. Dann können sich ausschließlich Nutzer anmelden, die bereits als externe Nutzer im OPC Router vorhanden sind, und Sie legen deren Rollen vorab fest – z.B. beim Start des Containers über OR_EXTERNAL_USER_ADMIN_EMAILS, OR_EXTERNAL_USER_EDITOR_EMAILS und OR_EXTERNAL_USER_OBSERVER_EMAILS.

Wenn ausschließlich Microsoft Entra ID für die Anmeldung verwendet werden soll, können INITIAL_USERNAME und INITIAL_PASSWORD entfallen.

hinweis

Damit die Authentifizierung über die Entra ID funktioniert, muss HTTPS auf dem Container eingerichtet sein – der Befehl enthält die dafür nötigen Argumente. Er erwartet Zertifikat und Schlüssel als https.pem und https.key im aktuellen Verzeichnis und gilt für eine Bash-Shell; wie Sie beides erzeugen, beschreibt HTTPS verwenden. Ersetzen Sie außerdem Domäne, Verzeichnis-ID und Anwendungs-ID durch Ihre eigenen Werte.

Nach erfolgreicher Einrichtung sollte unter dem Login-Button ein Button für die Anmeldung über Azure AD/Entra ID (1) erscheinen. Über diese Schaltfläche können sich Benutzer, die über den Entra ID Tenant hinzugefügt wurden, anmelden.

Wenn der Button nicht erscheint

Der Button wird nur eingeblendet, wenn die Entra-ID-Konfiguration vollständig ist. Prüfen Sie in dieser Reihenfolge:

• Sind alle drei Variablen gesetzt? AZURE_AD_DOMAIN, AZURE_AD_TENANT_ID und AZURE_AD_CLIENT_ID müssen im Container ankommen. Mit docker inspect lässt sich nachsehen, welche Umgebungsvariablen der Container tatsächlich erhalten hat.
• Läuft das Web Management über HTTPS? Ohne HTTPS ist die Anmeldung über Entra ID nicht möglich.

Erscheint der Button, führt die Anmeldung aber zu einer Fehlerseite von Microsoft, liegt es in aller Regel an einem dieser beiden Punkte:

• Die Umleitungs-URI stimmt nicht überein. Sie muss exakt der Adresse entsprechen, unter der das Web Management aufgerufen wird, einschließlich https://, Port und dem Endpunkt-Pfad (standardmäßig /signin-oidc). Eine Abweichung meldet Microsoft als Fehler zur Redirect-URI.
• Der Haken bei ID-Token fehlt. Ohne aktiviertes ID-Token auf der Registerkarte Authentifizierung der Anwendungsregistrierung erhält der OPC Router keine verwertbare Antwort.