Anleitung: SMTP-Versand mit OAuth2 Authentifizierung (ab V12.1.2)

Für Microsoft Exchange

• Microsoft 365 Tenant (Mandant).

• Zugriff auf das Entra Admin Center.

• Berechtigung zur App-Registrierung.

• Zugriff auf Exchange Online Powershell

Für Google

• Google Workspace oder Google-Konto.

• Berechtigung zur OAuth-Freigabe.

Automatische Validierung

Sobald Sie speichern/ändern, startet automatisch eine Validierung. Es öffnet sich ein Fenster, das den Ablauf/Status der Prüfung anzeigt:

Bei Google wird im Zuge der Validierung zusätzlich ein Browserfenster geöffnet, in dem Sie sich am Google-Konto anmelden müssen:


 Hinweis: Ein Browser muss auf dem System verfügbar sein – falls nicht, erscheint eine entsprechende Meldung.

• Nach der validierung wechseln Sie bitte in Einstellungsmodul > Konfiguration AP> Abschnitt Ausleihe
• Dort tragen Sie bitte im Parameter MailAbs eine gültige Absendeadresse ein.

Abschluss der Einrichtung

• Nach erfolgreicher Authentifizierung wird eine Test-E-Mail versendet.

• Die E-Mail geht an die in den E-Mail-Einstellungen hinterlegte Absenderadresse.

• Der E-Mail-Versand ist nun aktiv.

Erneute Authentifizierung

OAuth-Tokens können ablaufen, zum Beispiel bei längerer Inaktivität (bei Google nach ca. 6 Monaten, bei Exchange Online ist dies einstellbar).

In diesem Fall:

• Ist eine erneute Verifizierung notwendig.

• Die Verifizierung kann automatisch beim nächsten E-Mail-Versand ausgelöst werden.

• Auf dem Client öffnet sich dann erneut das Browserfenster zur Anmeldung.

App registrieren

1. Öffnen Sie das Entra Admin Center.

2. Registrieren Sie eine neue App.

3. Notieren Sie:

• Application (Client) ID
• Directory (Tenant) ID

Redirect URIs

• Legen Sie Redirect URIs für folgende Typen an:

  • Mobile/Desktop (für BIBLIOTHECAnext Zugriff)

    • https://login.microsoftonline.com/common/oauth2/nativeclient

  • Web (für OPEN Zugriff)

    • https://[SITEURL]/Providers/SmtpOAuthProviders/ExchangeOnline/Authorize.aspx

    • https://[SITEURL]

      [SITEURL] = Webadresse Ihres OPENs z.B. katalog.buecherei.de

Client Secret erstellen

1. Erstellen Sie ein Client Secret.
2. Kopieren Sie den Wert sofort, da er nur einmal sichtbar ist.
3. Tragen Sie ihn als SMTPOAuthClientPwd ein.

API-Berechtigungen

• Für OPEN:

  • Fügen Sie die benötigte "Microsoft Graph" Berechtigung hinzu. 

  •  Wählen Sie "Delegierte Berechtigung" aus.

  • Wählen Sie die Berechtigung für "SMTP.send" aus.

• Für BIBLIOTHECAnext:

  • Fügen Sie die benötigte "Office 365 Exchange Online" Berechtigung hinzu

  • Wählen Sie "Applikations Berechtigung" aus.

  • Wählen Sie Berechtigung für "SMTP.SendAsApp" aus.

  • Erteilen Sie am Ende die Admin Zustimmung.

SMTP für die App freigeben

1. Wechseln Sie zu Enterprise Applications.

2. Öffnen Sie die registrierte App.

3. Notieren Sie die Object ID (Hinweis: Die Object ID aus Enterprise Applications unterscheidet sich von der Object ID aus App Registrations .

4. Führen Sie die Konfiguration per PowerShell aus:

• Verbindung zu Exchange Online herstellen.

• Service Principal anlegen.

  • New-ServicePrincipal -AppId <APPLICATION_ID> -ServiceId <OBJECT_ID>

  • <APPLICATION_ID> =SMTPOAuthClientID

  • <OBJECT_ID> = Object ID aus Enterprise Applications

• Berechtigungen für das Postfach vergeben.

  • Get-ServicePrincipal | fl -> SID kopieren

  • Add-MailboxPermission -Identity "user@domain.com" -User <SID> -AccessRights FullAccess

• SMTP Client Authentication aktivieren.

Die konkreten Befehle entnehmen Sie Ihrer internen Exchange-Dokumentation.

Einrichtung für Google

1. Öffnen Sie die Google Cloud Console

2. Melden Sie sich mit dem Google-Konto an, das für den E-Mail-Versand verwendet werden soll.

3. Erstellen Sie ein neues Projekt (der Name ist frei wählbar) oder nutzen Sie ein bereits bestehendes.
   In dem Projekt muss nun die OAUTH Authentifizierung aktiviert, sowie jeweils ein "Client" für BIBLIOTHECAnext und OPEN angelegt werden.

4. Navigieren Sie zu APIs und Dienste → OAuth-Zustimmungsbildschirm und konfigurieren Sie:

• Support-E-Mail: E-Mail-Adresse des zuständigen Administrators
• Kontakt-E-Mail: E-Mail-Adresse des zuständigen Administrators
• Unter Zielgruppe: Fügen Sie die E-Mail-Adresse des Kontos hinzu, das für den E-Mail-Versand genutzt wird.
• Testnutzer -> Add users

5. Unter Datenzugriff: Fügen Sie folgenden Berechtigungsbereich manuell hinzu:
   • https://www.googleapis.com/auth/gmail.send

6. Für OPEN:

• Anwendungstyp: Webanwendung
• Name: beliebig wählbar
• Autorisierte Weiterleitungs-URIs:
  • https://[SITEURL]/Providers/SmtpOAuthProviders/GoogleMail/Authorize.aspx
• Kopieren Sie Client ID und Client Secret sofort nach der Erstellung (oder speichern Sie als JSON Datei) und bewahren Sie diese sicher auf – das Secret ist nur einmal sichtbar.

7. Für BIBLIOTHECAnext:

• Anwendungstyp: Desktopanwendung
• Name: beliebig wählbar
• Kopieren Sie Client ID und Client Secret sofort nach der Erstellung (oder speichern Sie als JSON Datei) und bewahren Sie diese sicher auf – das Secret ist nur einmal sichtbar.

Zuordnung der Werte

Fehlerbehebung

• Keine Browser-Anmeldung möglich > Prüfen Sie, ob ein Browser installiert ist.

• Validierung schlägt fehl. >Prüfen Sie Client-ID, Secret und Tenant-ID.

• E-Mails werden nicht versendet. > Prüfen Sie die SMTP-Freigaben und Postfachberechtigungen.

• Bei Google: Wenn im Browser Fenster länger wie 5 Minuten gebraucht wird, um sich am Konto anzumelden und die Verknüpfung zu BIBLIOTHECAnext herzustellen, muss es noch mal gemacht werden. Google hat hier einen Automatischen Timeout. 

Support

Wenn die Einrichtung trotz korrekter Konfiguration nicht erfolgreich ist, wenden Sie sich an den technischen Support und halten Sie folgende Informationen bereit:

• OAuth-Provider.

• Fehlermeldungen aus der Validierung.

• Zeitpunkt der letzten erfolgreichen Authentifizierung (falls es bereits funktioniert hatte).