Integration of grommunio into Existing SSO Environments
1. Introduction
With grommunio-auth, the platform is extended by an authentication layer based on Keycloak and supporting modern standards such as OpenID Connect. This means that grommunio is fundamentally capable of acting as an identity provider itself. In practice, however, this approach is rarely advisable.
In production environments, authentication should not be tied to individual applications. Users, passwords, multi-factor authentication, and security policies belong in a centralized instance. This is exactly where integration into an existing SSO environment comes into play. Instead of maintaining identities multiple times, grommunio is connected to an existing identity provider and uses it for all authentication processes.
This approach not only reduces administrative overhead, but also ensures consistent security mechanisms across all systems. Grommunio-auth is included starting with the Basic license.
2. Target Architecture
The integration is based on a classic identity broker model. In this setup, the Keycloak instance integrated into grommunio no longer acts as the primary identity provider, but instead functions as an intermediary.
Authentication requests are forwarded from grommunio-auth to the central identity provider. The actual login process — including password verification and optional multi-factor authentication — takes place there. After successful authentication, the user is redirected back to grommunio and granted access to the application.
The advantage of this architecture is that all security-related processes can be managed centrally, while grommunio acts solely as a service provider.
3. Best Practice: Integration with an Existing Identity Provider
Although it is technically possible to operate grommunio-auth independently, this approach is rarely recommended. Isolated authentication inevitably leads to duplicated user management, separate password policies, and additional administration of 2FA mechanisms.
Especially in environments with multiple services, this quickly results in a fragmented identity landscape. Changes to user accounts must be performed multiple times, security policies become inconsistent, and the risk of inconsistencies increases.
The clear best practice is therefore to integrate grommunio with an existing identity provider and use it as the central instance for authentication and authorization. In many environments, this is already an existing Keycloak deployment, but it can just as easily be any other OIDC-compatible provider.
4. Installation of grommunio-auth
The installation of grommunio-auth on the appliance can be performed using the following command in the CLI:
zypper install grommunio-auth
After the package has been installed, the configuration of grommunio-auth can begin:
/usr/share/grommunio-auth/setup-grommunio-auth.sh
The installation process is straightforward, just like the installation of the appliance itself. By default, grommunio-auth uses the appliance’s local MariaDB instance unless configured otherwise.
The configuration of the Fully Qualified Domain Name (FQDN) in the next step is essential. The hostname under which the webmail service is accessible should be entered here, for example webmail.forgeone.eu. This ensures that grommunio-auth will be reachable at:
https://webmail.forgeone.eu/auth/
Using the internal server hostname is generally not recommended, since the actual server name is often unknown or not resolvable for external access.
In the next step, a password can be defined. This password is used for the master realm in grommunio-auth. If no password is specified during installation, it will be displayed at the end of the installation process.
Since the master realm should not be accessible from everywhere, access can be restricted using IP subnet definitions. These settings can be modified at any time afterwards in:
/etc/grommunio-common/nginx/auth_allow.conf
If everything has worked correctly up to this point, you will see the login screen when accessing the grommunio webmail interface via:
https://webmail.forgeone.eu/web
Users will automatically be redirected to grommunio-auth for authentication.
For smaller environments, the installation process is complete at this point. In this setup, grommunio-auth uses the users stored in the grommunio database, either created through the grommunio administration interface or synchronized via LDAP.
The following steps describe the direct integration with an existing identity provider, such as a separate centralized Keycloak instance, where users may already have multi-factor authentication methods like TOTP or passkeys configured.
If any typo or configuration issue occurred during setup, the grommunio-auth configuration can be adjusted under:
/etc/grommunio-keycloak/
The following files can be found in this directory:
/etc/grommunio-keycloak/keycloak.conf
# SPDX-License-Identifier: AGPL-3.0-or-later# SPDX-FileCopyrightText: 2023 grommunio GmbHdb=mariadbproxy=edgehttp-port=9080http-relative-path=/authhttp-host=localhosthttp-enabled=truedb-username=grommunio_keycloakdb-password=k7OOsadisandsaIUHAISISdb-url-database=grommunio_keycloakdb-url-host=localhosthostname=webmail.forgeone.euhostname-strict=falsehostname-strict-https=falseproxy-headers=xforwarded
/etc/grommunio-keycloak/grommunio.properties
# SPDX-License-Identifier: AGPL-3.0-or-later# SPDX-FileCopyrightText: 2023 grommunio GmbHgrommunio.db-kind=org.mariadb.jdbc.Drivergrommunio.jdbc-url=jdbc:mariadb://localhost:3306/grommuniogrommunio.username=groauthgrommunio.password=Asjhdshdsya7GAGDSsytgasans
The hostname configuration can also be adjusted in:
/etc/gromox/keycloak.json
{"realm" : "grommunio","auth-server-url" : "https://webmail.forgeone.eu/auth/","ssl-required" : "external","resource" : "grommunio","verify-token-audience" : true,"credentials" : {"secret" : "sdsajdinsdiNAUSsasayna63424"},"confidential-port" : 0,"policy-enforcer" : {"credentials" : { }}}
Afterwards, restart grommunio-auth once to apply the changes:
systemctl restart grommunio-keycloak
5. Configuration in the Central Identity Provider
For the integration, a new client for grommunio must be created in the central identity provider. This client establishes the trust relationship between the two systems.
A critical part of the configuration is the correct definition of the redirect URI. This specifies where the identity provider is allowed to redirect the user after successful authentication. The URI must exactly match the broker endpoint of the grommunio Keycloak instance.
A typical example looks like this:
https://webmail.example.com/auth/realms/grommunio/broker/<alias>/endpoint
Even minor deviations can lead to errors at this stage, which is why this part of the configuration should be implemented with particular care. After creating the client, a client secret is generated as well, which will later be configured in the grommunio Keycloak instance.
6. Configuring the Identity Provider in grommunio Keycloak
On the grommunio side, a new identity provider is then configured. This identity provider points to the central Keycloak instance and uses its OpenID Connect discovery mechanism to automatically retrieve the required endpoints.
In addition to the client ID and secret, the choice of the alias is particularly important. The alias is used internally by the broker and must be referenced consistently throughout all further configurations.
In practice, settings such as an enforced synchronization mode and trusting the email addresses provided by the identity provider have proven to be especially useful. This ensures that user attributes are updated on every login and prevents unnecessary prompts during the authentication process.
7. Enforcing SSO and Disabling Local Login
After the integration has been completed successfully, the next step is to fully disable local logins. By default, Keycloak still allows authentication using local user accounts, which is generally not desirable in an SSO scenario.
This behavior is controlled through the so-called Browser Flow. The login process is adjusted so that authentication requests are immediately redirected to the configured identity provider. The central component for this setup is the Identity Provider Redirector, which is configured as a mandatory step in the authentication flow.
Once this has been configured correctly, local logins are no longer possible. Instead, every authentication request is delegated directly to the central identity provider. For users, this results in a consistent login experience across all connected systems.
8. Common Issues and Pitfalls
In practice, similar issues tend to occur repeatedly during integration. In many cases, the root cause is an incorrect redirect URI or a misconfigured browser flow. This can result in missing redirects or login failures with only generic error messages.
Another common issue is user mapping. grommunio expects users to exist in the backend and to be mapped correctly. If the attributes provided by the identity provider do not match the local user data, access may fail even though authentication itself was successful.
Direct access to Keycloak endpoints is also a frequent source of confusion, as users may end up in the Keycloak account console instead of the webmail interface. The important point here is that access should always start through the actual application.
9. Conclusion
Integrating grommunio into an existing SSO environment is not merely an optional feature, but the recommended operating model for production systems. It reduces complexity, avoids redundant configurations, and establishes a clear separation between the application itself and identity management.
Organizations that already operate a centralized identity solution should consistently use it for grommunio as well. The result is a significantly more stable and easier-to-maintain environment with unified security standards.
10. Forecast
The next article will cover another key aspect of running a mail server: spam filtering. We will take a detailed look at grommunio-antispam and rspamd, and demonstrate how deliverability, reputation, and filtering quality can be improved in a targeted and effective way.
