OAuth 2.0 – Grundlagen

Diese Seite erklärt die OAuth-2.0-Grundlagen im Kontext des OPC Routers. Sie dient als gemeinsame Referenz und erklärt die wiederkehrenden Begriffe und Verfahren einmal zentral. Welche Plug-ins den Token selbst holen und welche einen fertigen Token nur weiterreichen, steht unter Konfiguration im OPC Router.

OAuth 2.0 ist ein Standard, mit dem sich eine Anwendung an einem Zielsystem anmeldet, ohne ein festes Passwort mitzusenden. Stattdessen holt sie sich an einer zentralen Stelle ein zeitlich begrenztes Access Token und weist sich damit gegenüber dem Zielsystem aus.

Rollen

Im OPC-Router-Kontext sind drei Rollen beteiligt:

Rolle	Bedeutung	Im OPC Router
Client	Fordert das Token an und verwendet es.	Der OPC Router bzw. das jeweilige Plug-in.
Authorization Server	Stellt nach erfolgreicher Anmeldung das Access Token aus.	Der Token-Endpunkt des Identity-Providers (z. B. Microsoft Entra ID).
Resource Server	Prüft das Token und liefert die eigentlichen Daten.	Das angebundene Zielsystem (z. B. REST-API oder Mailserver).

Client Credentials Flow (E-Mail-Plug-ins)

Der Client Credentials Flow ist das Verfahren für Verbindungen, die ohne Benutzer auskommen: Der OPC Router meldet sich als registrierte Anwendung an, ohne interaktive Anmeldung, denn zur Laufzeit läuft er unbeaufsichtigt und ohne Browser.

In Version 5.7 holt sich damit das E-Mail-Plug-in seinen Token – für den Versand ebenso wie für den E-Mail-Trigger. Beide bieten daneben den Device-Code-Fluss an, der Trigger zusätzlich die Anmeldung mit Benutzername und Passwort sowie den Client-Credentials-Fluss wahlweise mit einem Zertifikat statt eines Secrets.

1. Das Plug-in fordert ein Token an und weist sich dabei mit Client ID, Client Secret und Tenant ID aus (grant_type=client_credentials). Den Aufruf übernimmt die Microsoft-Bibliothek; die Adresse des Endpunkts ergibt sich aus der Tenant ID.
2. Der Authorization Server antwortet mit einem Access Token und dessen Gültigkeitsdauer.
3. Das Plug-in authentifiziert mit dem Token die Sitzung zum Mailserver – über das SASL-Verfahren XOAUTH2, nicht über einen HTTP-Header. Erst auf der authentifizierten Sitzung werden Mails gesendet oder abgeholt.
4. Ein Token fällt je Verbindungsaufbau an, also je Transfer, und nicht je Mail. Die Gültigkeitsdauer wertet der OPC Router nicht aus; er erneuert kein Token vorzeitig.

Begriffe

Begriff	Bedeutung
Tenant ID	Eindeutige Kennung des Mandanten (Verzeichnisses) beim Identity-Provider. Ordnet die Anmeldung dem richtigen Mandanten zu; relevant vor allem bei Microsoft Entra ID.
Client ID	Eindeutige Anwendungskennung des registrierten Clients. Identifiziert die Anwendung gegenüber dem Authorization Server.
Client Secret	Geheimnis des registrierten Clients zur Authentifizierung am Token-Endpunkt. In einem Plug-in mit eigenen OAuth-Feldern hinterlegen Sie es dort als Secret; bei manuell projektiertem Token-Abruf legen Sie es in einer Variable vom Typ Secret String ab (Secrets).
Authority URI	Basisadresse des Identity-Providers, aus der sich die konkreten Endpunkte (u. a. der Token-Endpunkt) ergeben.
Token URL	Konkreter Endpunkt, an dem das Access Token angefordert wird.
Redirect URI	Adresse, an die der Authorization Server nach einer interaktiven Anmeldung zurückleitet. Nur bei benutzergebundenen Verfahren relevant, nicht beim Client Credentials Flow.
Scopes	Liste der angeforderten Berechtigungen. Sie müssen zur Registrierung des Clients und zum Zielsystem passen.
Access Token	Zeitlich begrenztes Token, das die Anwendung dem Zielsystem als Nachweis mitsendet.

Anmeldung am Web Management (OpenID Connect)

Die Anmeldung am Web Management (der Konfigurationsoberfläche) ist ein interaktives Verfahren: Ein Benutzer meldet sich im Browser beim Identity-Provider an, etwa per Single Sign-on über Microsoft Entra ID (siehe Microsoft Entra ID/Azure AD anbinden).

Der OPC Router benutzt dafür OpenID Connect und fordert genau ein ID-Token an, das den angemeldeten Benutzer beschreibt. Einen Autorisierungscode gibt es dabei nicht, und ein Access Token wird nicht ausgestellt: Das ID-Token kommt unmittelbar an der Redirect URI an, vom Browser als Formular gesendet.

hinweis

Dieses Verfahren gilt nur für die Anmeldung am Web Management und hat mit der Anmeldung einer Plug-in-Verbindung nichts zu tun. Eine Plug-in-Verbindung holt ihr Token selbst (Client Credentials) oder bekommt es projektiert. Der Device-Code-Fluss der E-Mail-Plug-ins ist ein dritter Fall: Dort meldet sich einmalig ein Benutzer an einem beliebigen Gerät an, danach läuft die Verbindung wieder unbeaufsichtigt.

1. Ruft ein Benutzer eine geschützte Seite auf, leitet das Web Management seinen Browser zum Identity-Provider um – mit Client ID, Redirect URI und Scope und mit der Angabe, dass ein ID-Token angefordert wird.
2. Der Benutzer meldet sich an und bestätigt die angeforderten Berechtigungen.
3. Der Identity-Provider stellt das ID-Token aus und schickt es an die Redirect URI; der Browser überträgt es als Formular an das Web Management.
4. Das Web Management prüft das ID-Token und stellt daraufhin ein eigenes Anwendungs-Cookie aus. Die weitere Sitzung läuft über dieses Cookie, ohne weiteren Verkehr zum Identity-Provider.

Für die Registrierung im Identity-Provider heißt das: Die Anwendung muss ID-Tokens ausstellen dürfen, und ein Client Secret wird nicht benötigt.

Abgrenzung zu Basic Authentication

Bei der Basic Authentication sendet der Client bei jedem Aufruf Benutzername und Passwort (Base64-kodiert) mit. Es gibt kein Token, keine Ablaufzeit und keine feingranularen Berechtigungen.

OAuth 2.0 trennt dagegen die Anmeldung (einmalig am Token-Endpunkt) von der Nutzung (Access Token bei jedem Aufruf). Das Token ist zeitlich begrenzt und über Scopes auf bestimmte Berechtigungen eingeschränkt. Das Passwort selbst wird nicht an das Zielsystem übertragen.

Konfiguration im OPC Router

Je nach Plug-in wird OAuth 2.0 auf zwei Arten bereitgestellt:

• Nativ konfiguriert: Das Plug-in besitzt eigene Felder für den Flow. Im E-Mail-Plug-in tragen Sie Client ID, Client Secret und Tenant ID ein; den Token-Abruf übernimmt das Plug-in. Für die vorbereiteten Microsoft-Anbieter sind die Scopes fest vorgegeben; frei wählbar sind sie nur auf der Registerkarte für die benutzerdefinierte Anbindung.
• Manuell projektiert: Der REST-Client führt selbst keine OAuth-Anmeldung durch. Sie holen das Token bei Bedarf über einen eigenen REST-Aufruf und reichen es als Bearer-Token weiter; das Plug-in hängt es unverändert an den Aufruf. Ein durchgängiges Beispiel steht unter Verbindung mit Bearer Token.

Beispiele

Microsoft 365 / Entra ID

Für Microsoft-365- bzw. Entra-ID-Umgebungen registrieren Sie eine Anwendung im Microsoft Entra Admin Center und erhalten dort Tenant ID, Client ID und Client Secret. Der Token-Endpunkt hat die Form https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token, als Scope wird häufig ein Wert mit der Endung /.default verwendet. Das Anbinden ist unter Microsoft Entra ID/Azure AD anbinden beschrieben.

Generische OAuth-Anbieter

Bei anderen Anbietern gelten dieselben Begriffe. Token URL, Client ID, Client Secret und die zulässigen Scopes entnehmen Sie der Dokumentation des jeweiligen Providers und tragen sie im Plug-in ein bzw. verwenden sie im REST-Aufruf.