OAuth Einrichtung

Geschätzte Lektüre: 12 Minuten 5 Ansichten

OAuth-Einrichtung für den E-Mail Controller

Diese Anleitung beschreibt die vollständige Einrichtung von OAuth 2.0 für SMTP auf dem Gira X1. Sie richtet sich an Administratoren. Die Einrichtung erfolgt einmalig an einem PC mit Browser; auf dem X1 findet keine interaktive Anmeldung statt.

1. Funktionsweise

Der Baustein speichert einen OAuth-Refresh-Token als GPA-Parameter. Unmittelbar vor jeder E-Mail sendet er über das System-curl folgenden formularcodierten HTTPS-Request an den Token-Endpunkt:

grant_type=refresh_token
client_id=<Client-ID>
client_secret=<optional>
refresh_token=<Refresh-Token>
scope=<optional>

Der Provider antwortet mit einem kurzlebigen access_token. MailKit verwendet diesen anschließend für AUTH XOAUTH2 am SMTP-Server. Das Kontokennwort wird dabei nicht an den SMTP-Server gesendet.

Der Baustein führt keinen Authorization-Code-, PKCE-, Device-Code- oder Consent-Ablauf durch. Er benötigt einen zuvor extern erzeugten Refresh-Token. Unterstützt werden deshalb delegierte OAuth-Abläufe mit grant_type=refresh_token. Ein reiner Client-Credentials-/App-only-Ablauf ohne Refresh-Token wird nicht unterstützt.

2. Voraussetzungen

Vor der Einrichtung müssen alle folgenden Punkte erfüllt sein:

Der Provider unterstützt SMTP und AUTH XOAUTH2.
Für das Konto ist authentifizierter SMTP-Versand erlaubt.
Ein OAuth-Client darf den notwendigen SMTP-Scope anfordern.
Der Autorisierungsablauf liefert durch Offline-Zugriff einen Refresh-Token.
Der X1 erreicht den Token-Endpunkt über HTTPS und den SMTP-Server über den gewählten Port.
Datum, Uhrzeit und DNS des X1 stimmen.

OAuth für eine REST-Mail-API wie Microsoft Graph oder Gmail API allein reicht nicht aus. Der ausgestellte Access-Token muss ausdrücklich für den SMTP-/XOAUTH2-Dienst des Providers gelten.

3. Bedeutung aller GPA-Felder

Feld	Beschreibung	Beispiel
`Authentication`	Für OAuth immer `OAuth2 Refresh Token`.	`OAuth2 Refresh Token`
`SMTP server`	Hostname des SMTP-Dienstes.	`smtp.gmail.com`
`SMTP port`	Üblicherweise 587 mit STARTTLS oder 465 mit TLS ab Verbindungsbeginn.	`587`
`Encryption`	Muss zu Port und Provider passen.	`STARTTLS`
`SMTP user`	Identität im XOAUTH2-Login, normalerweise vollständige E-Mail-Adresse.	`alarm@example.com`
`From`	Absender; muss identisch oder als Send-as-Adresse erlaubt sein.	`alarm@example.com`
`OAuth client ID`	ID genau des Clients, mit dem der Refresh-Token erzeugt wurde.	Providerwert
`OAuth client secret`	Nur für vertrauliche Clients. Bei öffentlichen Clients leer.	Providerwert
`OAuth refresh token`	Langfristiges Geheimnis aus dem externen Consent-Ablauf.	Nicht dokumentieren
`OAuth token endpoint`	HTTPS-Endpunkt für den Token-Refresh.	Providerabhängig
`OAuth scope (optional)`	Beim Refresh erneut anzufordernder SMTP-Scope. Leer lassen, wenn der Provider das nicht verlangt.	Providerabhängig
`OAuth client authentication`	Übertragung der Client-Zugangsdaten: `Form`, `Basic` oder `None`.	`Form`
`Timeout`	Gemeinsamer Timeout für Token- und SMTP-Verbindung.	`30 s`

Client-Authentifizierung auswählen

Form: client_id und client_secret stehen im Request-Body. Das ist die Voreinstellung und passt unter anderem zu einem vertraulichen Google-Client.
Basic: Client-ID und Secret werden als HTTP Basic Authentication übertragen; client_id wird dabei nicht zusätzlich in den Body geschrieben.
None: öffentlicher Client ohne Secret. client_id bleibt im Body. Das ist das unten beschriebene Microsoft-Device-Code-Beispiel.

Die Einstellung betrifft die Authentifizierung des OAuth-Clients am Token-Endpunkt, nicht die spätere XOAUTH2-Anmeldung am SMTP-Server.

4. Google Gmail und Google Workspace

Google unterstützt SMTP-XOAUTH2 mit dem Scope https://mail.google.com/. Der SMTP-Server ist smtp.gmail.com; Google dokumentiert Port 465 für SSL/TLS und Port 587 für STARTTLS.

4.1 Google-Cloud-Projekt vorbereiten

In der Google Cloud Console ein separates Projekt anlegen oder auswählen.
Unter Google Auth Platform den OAuth-Zustimmungsbildschirm konfigurieren.
Bei Google Workspace möglichst den Zielgruppentyp Intern verwenden, wenn ausschließlich Benutzer der eigenen Organisation senden sollen.
Bei Extern das sendende Konto als Testnutzer hinzufügen, solange sich die App im Teststatus befindet.
Den Scope https://mail.google.com/ in die Data-Access-/Scope-Konfiguration aufnehmen.
Unter Clients/Credentials einen OAuth-Client vom Typ Web application anlegen.
Als autorisierte Redirect-URI exakt eintragen:

https://developers.google.com/oauthplayground

Client-ID und Client-Secret sicher speichern.

Der Gmail-SMTP-Scope ist weitreichend und wird von Google als eingeschränkt behandelt. Für öffentlich vertriebene Anwendungen kann eine Google-Verifizierung erforderlich sein. Bei einem externen Projekt im Status Testing können Refresh-Tokens nach sieben Tagen ablaufen. Für einen dauerhaften Produktivbetrieb müssen Zielgruppe, Veröffentlichungsstatus und Verifizierung zur Organisation passen.

4.2 Refresh-Token mit dem offiziellen OAuth Playground erzeugen

Den Google OAuth 2.0 Playground öffnen.
Oben rechts OAuth 2.0 configuration öffnen.
Use your own OAuth credentials aktivieren.
Die eben erstellte Client-ID und das Client-Secret eintragen.
Access type = Offline wählen.
Für eine erneute Ausstellung bei bestehendem Grant Force prompt = Consent Screen wählen.
Im linken Feld Input your own scopes exakt eintragen:

https://mail.google.com/

Authorize APIs wählen.
Mit genau dem Google-Konto anmelden, das später unter SMTP user verwendet wird.
Die Berechtigung bestätigen.
In Schritt 2 Exchange authorization code for tokens wählen.
Den angezeigten Refresh token sicher kopieren. Access-Token und Authorization Code werden im GPA nicht benötigt.

Wird kein Refresh-Token angezeigt, sind meistens kein Offline-Zugriff oder kein erneuter Consent aktiv. Alternativ den bestehenden Grant im Google-Konto widerrufen und den Ablauf wiederholen. Der Playground widerruft eigene Playground-Tokens nach kurzer Zeit; deshalb müssen unbedingt die eigenen OAuth-Clientdaten verwendet werden.

4.3 GPA-Konfiguration für Google

Feld	Wert
`SMTP server`	`smtp.gmail.com`
`SMTP port`	`587`
`Encryption`	`STARTTLS`
`Authentication`	`OAuth2 Refresh Token`
`SMTP user`	vollständige Gmail-/Workspace-Adresse
`From`	dieselbe Adresse oder erlaubter Alias
`OAuth client ID`	Client-ID aus Google Cloud
`OAuth client secret`	Client-Secret aus Google Cloud
`OAuth refresh token`	Refresh-Token aus dem Playground
`OAuth token endpoint`	`https://oauth2.googleapis.com/token`
`OAuth scope (optional)`	normalerweise leer; bei Bedarf `https://mail.google.com/`
`OAuth client authentication`	`Form`

Alternative Transportkonfiguration: Port 465 mit SSL/TLS. Port 587 mit STARTTLS ist für die übliche Client-Submission vorzuziehen.

4.4 Google-Beispielmail

To: empfaenger@example.net
From: alarm@example.com
Subject: X1-Test {{Value1}}
Body: OAuth-Test erfolgreich. Anlagenstatus: {{Value2}}

Nach dem Setzen des Triggers muss Status zunächst Sending... und anschließend Message sent anzeigen; Success wird 1.

5. Microsoft 365 und Exchange Online

Für delegierten SMTP-Versand lautet der Microsoft-Scope https://outlook.office.com/SMTP.Send. Zusätzlich muss beim ersten Ablauf offline_access angefordert werden, damit Microsoft einen Refresh-Token ausstellt. Der folgende Weg verwendet einen öffentlichen Client und den Device-Code-Flow, also kein Client-Secret.

5.1 App in Microsoft Entra registrieren

Im Microsoft Entra Admin Center zu Identity > Applications > App registrations wechseln.
New registration wählen.
Einen eindeutigen Namen wie Gira X1 Email Controller vergeben.
Für einen Unternehmenstenant normalerweise Accounts in this organizational directory only wählen.
Registrierung abschließen und folgende Werte notieren:
- Application (client) ID
- Directory (tenant) ID
Unter API permissions > Add a permission zu APIs my organization uses wechseln.
Office 365 Exchange Online auswählen.
Delegated permissions und anschließend SMTP.Send hinzufügen.
Falls die Mandantenrichtlinie es verlangt, Grant admin consent ausführen.
Unter Authentication > Advanced settings die Option Allow public client flows aktivieren.

Für dieses Device-Code-Beispiel wird unter Certificates & secrets kein Client-Secret angelegt. Conditional Access kann Device Code blockieren; in diesem Fall muss der Entra-Administrator einen zulässigen delegierten Authorization-Code-Ablauf bereitstellen.

5.2 SMTP AUTH für das Postfach erlauben

Microsoft 365 Admin Center:

Users > Active users öffnen.
Das sendende Konto auswählen.
Mail > Manage email apps öffnen.
Authenticated SMTP aktivieren und speichern.

Alternativ mit Exchange Online PowerShell:

Set-CASMailbox -Identity alarm@contoso.com -SmtpClientAuthenticationDisabled $false
Get-CASMailbox -Identity alarm@contoso.com | Format-List SmtpClientAuthenticationDisabled

Der Prüfwert muss False sein. Die Postfacheinstellung überschreibt die organisationsweite Einstellung. Security Defaults oder Conditional-Access-Regeln können den Ablauf zusätzlich verhindern und müssen vom Tenant-Administrator bewertet werden.

5.3 Refresh-Token per Device Code erzeugen

Das folgende Beispiel wird an einem administrierten Windows-PC ausgeführt. Platzhalter ersetzen; das Skript schreibt den Refresh-Token am Ende in die Konsole. Konsolenverlauf und Bildschirmaufzeichnung entsprechend schützen.

$tenantId = '<Directory-Tenant-ID>'
$clientId = '<Application-Client-ID>'
$scope = 'offline_access https://outlook.office.com/SMTP.Send'
$base = "https://login.microsoftonline.com/$tenantId/oauth2/v2.0"

$device = Invoke-RestMethod -Method Post -Uri "$base/devicecode" -Body @{
    client_id = $clientId
    scope = $scope
}

Write-Host $device.message
$deadline = (Get-Date).AddSeconds([int]$device.expires_in)
$interval = [Math]::Max(5, [int]$device.interval)
$token = $null

while (-not $token -and (Get-Date) -lt $deadline) {
    Start-Sleep -Seconds $interval
    try {
        $token = Invoke-RestMethod -Method Post -Uri "$base/token" -Body @{
            grant_type = 'urn:ietf:params:oauth:grant-type:device_code'
            client_id = $clientId
            device_code = $device.device_code
        }
    }
    catch {
        $oauthError = $null
        try { $oauthError = $_.ErrorDetails.Message | ConvertFrom-Json } catch { }
        if ($oauthError.error -eq 'authorization_pending') { continue }
        if ($oauthError.error -eq 'slow_down') { $interval += 5; continue }
        throw
    }
}

if (-not $token -or -not $token.refresh_token) {
    throw 'Kein Refresh-Token empfangen. offline_access, Public-Client-Flow und Consent prüfen.'
}

Write-Host 'Refresh-Token (vertraulich):'
Write-Host $token.refresh_token

Nach Ausgabe der Microsoft-Anweisung im Browser https://microsoft.com/devicelogin öffnen, den Code eingeben, mit dem sendenden Postfach anmelden und den Consent bestätigen. Der erhaltene Access-Token wird nicht benötigt; ausschließlich der Refresh-Token kommt in den GPA.

5.4 GPA-Konfiguration für Microsoft 365

Feld	Wert
`SMTP server`	`smtp.office365.com`
`SMTP port`	`587`
`Encryption`	`STARTTLS`
`Authentication`	`OAuth2 Refresh Token`
`SMTP user`	vollständige Microsoft-365-Adresse
`From`	dieselbe Adresse oder erlaubte Send-as-Adresse
`OAuth client ID`	Application (client) ID
`OAuth client secret`	leer
`OAuth refresh token`	Ausgabe des Device-Code-Skripts
`OAuth token endpoint`	`https://login.microsoftonline.com/<Tenant-ID>/oauth2/v2.0/token`
`OAuth scope (optional)`	`https://outlook.office.com/SMTP.Send`
`OAuth client authentication`	`None`

Für Unternehmensmandanten die konkrete Tenant-ID verwenden, nicht common. So ist eindeutig festgelegt, welcher Mandant den Token ausstellt.

5.5 Wichtige Microsoft-Abgrenzung

Microsoft dokumentiert zusätzlich SMTP.SendAsApp mit Client-Credentials für App-only-Zugriff. Dieser Ablauf gibt keinen Refresh-Token aus und ist daher nicht mit dem Modus OAuth2 Refresh Token dieses Bausteins kompatibel. Für diesen Baustein wird der delegierte Scope SMTP.Send verwendet.

6. Andere Provider

Vor der Einrichtung die OAuth-/SMTP-Dokumentation des Providers anhand dieser Checkliste prüfen:

Frage	Benötigte Antwort
Unterstützt SMTP `AUTH XOAUTH2`?	Ja
Gibt es einen delegierten Offline-Ablauf?	Er muss einen Refresh-Token liefern.
Welcher Scope autorisiert SMTP-Senden?	Exakten Scope des Providers verwenden.
Wie authentifiziert sich der Client am Token-Endpunkt?	`Form`, `Basic` oder `None` passend einstellen.
Muss `scope` beim Refresh erneut gesendet werden?	Falls ja, `OAuth scope` setzen.
Stimmen SMTP-Benutzer und Token-Identität überein?	Normalerweise müssen sie identisch sein.

Beispiel für einen generischen vertraulichen Client:

SMTP server: mail.example.org
SMTP port: 587
Encryption: STARTTLS
Authentication: OAuth2 Refresh Token
SMTP user: alarm@example.org
OAuth client ID: x1-email-controller
OAuth client secret: <geheim>
OAuth refresh token: <geheim>
OAuth token endpoint: https://id.example.org/oauth2/token
OAuth scope: smtp.send
OAuth client authentication: Basic

Nicht jeder Provider nennt das Verfahren XOAUTH2; entscheidend ist, dass der SMTP-Server das SASL-Verfahren XOAUTH2 anbietet und der Access-Token dafür ausgestellt wird. OAUTHBEARER ohne XOAUTH2 wird derzeit nicht verwendet.

7. Sichere Vorabprüfung des Token-Refreshs

Vor dem X1 kann der Refresh-Request an einem administrierten PC geprüft werden. Geheimnisse nicht in Tickets, Screenshots oder dauerhaftem Shell-Verlauf speichern.

Form-Authentifizierung:

curl.exe --http1.1 --fail-with-body -X POST `
  -H "Content-Type: application/x-www-form-urlencoded" `
  --data-urlencode "client_id=<CLIENT-ID>" `
  --data-urlencode "client_secret=<CLIENT-SECRET>" `
  --data-urlencode "refresh_token=<REFRESH-TOKEN>" `
  --data-urlencode "grant_type=refresh_token" `
  "<TOKEN-ENDPOINT>"

Erwartet wird HTTP 200 mit mindestens:

{
  "access_token": "...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Ein möglicherweise zusätzlich zurückgegebener neuer refresh_token wird vom Baustein nicht automatisch in die GPA-Konfiguration zurückgeschrieben. Wenn ein Provider alte Refresh-Tokens bei Rotation sofort ungültig macht, muss dessen Token-Lebenszyklus gesondert berücksichtigt werden.

8. Inbetriebnahme auf dem X1

OAuth-Werte im GPA vollständig eintragen.
Projekt auf den X1 übertragen.
LicenseInfo abwarten; Versand erst bei gültiger Lizenz testen.
To, From, Subject und Body mit neutralen Testdaten füllen.
Trigger einmal auf 1 setzen.
Status und Success auswerten.
Erst danach dynamische Werte und produktive Empfänger anschließen.

Bei Tests keine Secrets in Body, Subject, Status oder Gruppenadressen kopieren.

9. Fehlerdiagnose

Meldung / Symptom	Wahrscheinliche Ursache	Maßnahme
`invalid_client`	Client-ID, Secret oder Authentifizierungsart falsch.	Clientdaten und `Form`/`Basic`/`None` abgleichen.
`invalid_grant`	Refresh-Token widerrufen, abgelaufen, falscher Client/Tenant oder Uhrzeit falsch.	Consent erneut durchführen; Client-/Tenant-Zuordnung prüfen.
`invalid_scope`	Scope falsch, falsche Ressource oder nicht freigegeben.	Exakten SMTP-Scope verwenden und Consent/API Permission prüfen.
`unauthorized_client`	Flow für App nicht erlaubt.	Google-Clienttyp bzw. Microsoft Public Client Flow prüfen.
OAuth-Refresh erfolgreich, SMTP 535/401	Token besitzt nicht den SMTP-Scope, SMTP user passt nicht oder SMTP AUTH ist deaktiviert.	Scope, Kontoidentität und Provider-SMTP-Freigabe prüfen.
`AuthenticationException`	SMTP lehnt XOAUTH2 ab.	SMTP-Host, Port, Verschlüsselung, SMTP-AUTH und Send-as prüfen.
Timeout / `SocketException`	DNS, Firewall, Routing oder falscher Port.	X1-Netzzugriff auf HTTPS/443 und SMTP-Port testen.
Google liefert keinen Refresh-Token	Kein Offline-Zugriff oder Grant besteht bereits.	Eigenen Client im Playground, Offline und Consent aktivieren bzw. Grant widerrufen.
Microsoft liefert keinen Refresh-Token	`offline_access` fehlt oder ungeeigneter Flow.	Scope und Public-Client-/Device-Code-Konfiguration prüfen.
Microsoft `5.7.3 Authentication unsuccessful`	SMTP AUTH/Consent/Conditional Access verhindert Anmeldung.	Postfachsetting, Tenant-Richtlinien und Sign-in Logs prüfen.

10. Rotation, Widerruf und Datenschutz

Refresh-Token wie ein Kennwort behandeln und nur im GPA-Projekt sowie in einem freigegebenen Secret-Store ablegen.
Client-Secret und Refresh-Token nicht per unverschlüsselter E-Mail versenden.
Bei Mitarbeiterwechsel, Geräteübergabe oder Verdacht auf Offenlegung den Grant beim Provider widerrufen und neue Werte erzeugen.
Änderungen an Client-ID, Secret, Tenant oder Redirect-URI können eine neue Autorisierung erforderlich machen.
Nach Rotation immer eine Testmail senden und den alten Grant anschließend widerrufen.
Das sendende Konto nach dem Least-Privilege-Prinzip ausschließlich für den vorgesehenen Automationszweck verwenden.

11. Offizielle Referenzen

Google: OAuth 2.0 für Web-Server-Anwendungen
Google: OAuth 2.0 Playground
Google: OAuth 2.0 für Gmail SMTP/XOAUTH2
Google: Gmail SMTP-Server und Ports
Microsoft: IMAP, POP und SMTP mit OAuth authentifizieren
Microsoft: OAuth Device Authorization Grant
Microsoft: SMTP AUTH in Exchange Online aktivieren oder deaktivieren
Microsoft: Scopes und offline_access

Stand der Providerprüfung: 17. Juli 2026.