With the help of the OAuth2 extension for Benno MailArchiv, authentication via OAuth2 / OIDC against a central Identity Provider (e.g. Google, Microsoft Azure or Keycloak in own installations) can be performed.

The IDP typically also offers easy configuration of two-factor authentication.

Zur Aktivierung von OAuth2 wird das Paket benno-oauth2 benötigt.

apt install benno-oauth2

Das Paket installiert neben den benötigten Programmdateien Konfigurationsdateien im Verzeichnis /etc/benno-oauth2/. Hier wird die Anbindung an den IDP konfiguriert sowie das Mapping von Containern zum OAuth2 Issuer der User eingestellt.

In der Konfigurationsdatei /etc/benno-oauth2/idpClient.yml wird für den entsprechenden IDP-Provider im Attribut redirectURI der aus dem Internet erreichbare Hostname des Benno MailArchiv Systems eingetragen. Die Redirect-URI muss anschließend beim IDP in der Client-Registrierung gespeichert werden.

The Benno MailArchiv installation must be registered as a client in the corresponding interface of the IDP. The configuration of OAuth2 clients can be found in the documentation of the respective IDP.

Nach Einrichtung des Clients können hier die benötigten Verbindungsdaten wie clientID und clientSecret ausgelesen werden. Diese werden dann in der Konfigurationsdatei /etc/benno-oauth2/idpClients.yml in die entsprechenden Attribute eingetragen. Die anderen Einträge in der Konfigurationsdatei müssen in der Regel nicht angepasst werden.

Die Anmeldung per OAuth2 an Benno MailArchiv erfolgt über den Link https:// clients: ersetzt (Bsp. azure-idp, google-idp, keycloak-idp).

Falls die Datei /etc/benno-oauth2/assets/login.tpl existiert, wird der Inhalt dieser Datei in die Loginseite von Benno Web eingeblendet. Diese Datei sollte ein Smarty Template Snippet analog zu den tpl-Dateien in /usr/share/benno-oauth2/*.tpl sein. Für Standard-Konfigurationen kann ein ensprechender Symlink erstellt werden.

Example Google Login:

ln -s /usr/share/benno-oauth2/google-login.tpl /etc/benno-oauth2/assets/login.tpl
ln -s /usr/share/benno-oauth2/google-logo.svg  /etc/benno-oauth2/assets/google-logo.svg

Das Contianer-Mapping wird durch das automatisch installiert AUTH-Script /etc/benno-web/auth.d/10_oauth2_containermapping implementiert. Dieses liest die Datei /etc/benno-oauth2/issuer.map und gibt den Container anhand der Issuer-ID des Accesstoken zurück.

Per Default wird für jeden User der Standard-Container BennoContainer gesetzt.

If Benno MailArchiv is operated as a multi-tenant system, the line “* BennoContainer” must be removed and the issuer container information must be configured.

The AUTH script implements the Benno authentication protocol and can therefore be easily replaced or extended by custom-adapted scripts.