From ff564e3e65470bd9fe4eb15bcc8e6cc36fa2774f Mon Sep 17 00:00:00 2001 From: Tobias Krug Date: Mon, 18 May 2026 02:14:34 +0200 Subject: [PATCH] website/integrations: add grommunio (#22342) * docs: add grommunio integration guide * docs: fix prettier formatting in grommunio integration guide * Update formatting, change certificate section to match other docs, update some wording * Update. Co-authored-by: Agent --------- Co-authored-by: Tobias Krug Co-authored-by: Dewi Roberts Co-authored-by: Dominic R Co-authored-by: Agent --- locale/en/dictionaries/integrations.txt | 1 + .../grommunio/index.md | 170 ++++++++++++++++++ 2 files changed, 171 insertions(+) create mode 100644 website/integrations/chat-communication-collaboration/grommunio/index.md diff --git a/locale/en/dictionaries/integrations.txt b/locale/en/dictionaries/integrations.txt index 5926b43bc7..f2bc6da846 100644 --- a/locale/en/dictionaries/integrations.txt +++ b/locale/en/dictionaries/integrations.txt @@ -22,6 +22,7 @@ Gestionnaire ghec Gitea Gravitee +grommunio HACS Homarr Informatique diff --git a/website/integrations/chat-communication-collaboration/grommunio/index.md b/website/integrations/chat-communication-collaboration/grommunio/index.md new file mode 100644 index 0000000000..3671d94f37 --- /dev/null +++ b/website/integrations/chat-communication-collaboration/grommunio/index.md @@ -0,0 +1,170 @@ +--- +title: Integrate with grommunio +sidebar_label: grommunio +support_level: community +--- + + + +## What is grommunio? + +> grommunio is an open-source groupware server and collaboration platform offering email, calendar, contacts, tasks, video conferencing, and file sync. It is fully compatible with Microsoft Outlook via MAPI/RPC, EWS, and ActiveSync. +> +> -- https://grommunio.com/ + +## Preparation + +The following placeholders are used in this guide: + +- `grommunio.company` is the FQDN of the grommunio installation. +- `authentik.company` is the FQDN of the authentik installation. + +:::info +This documentation lists only the settings that you need to change from their default values. Be aware that any changes other than those explicitly mentioned in this guide could cause issues accessing your application. +::: + +## authentik configuration + +To integrate authentik with grommunio, you will need to create an application and provider pair in authentik. + +:::info Keycloak-compatible endpoints +grommunio-web expects Keycloak-compatible OIDC endpoints. Because authentik does not use Keycloak's `/realms/` endpoint structure, this guide configures an nginx bridge on the grommunio server. +::: + +### Create an application and provider in authentik + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **New Application** to open the application wizard. + - **Application**: provide a descriptive name (e.g., `grommunio`), an optional group, and the policy engine mode. + - **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. + - **Configure the Provider**: provide a name, the authorization flow to use, and the following required configurations. + - Note the **Client ID** and **Client Secret** values because they will be required later. + - Set a `Strict` redirect URI to `https://grommunio.company/web`. + - Set **Signing Key** to an available RSA key. + - Under **Advanced protocol settings**: + - Add the `authentik default OAuth Mapping: OpenID 'offline_access'` scope to **Selected Scopes**. + - **Configure Bindings** _(optional)_: create a binding to manage access. + +3. Click **Submit** to save the new application and provider. + +### Download certificate file + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Applications** > **Providers** and click on the name of the provider that you created in the previous section. +3. Under **Related objects** > **Download signing certificate**, click on **Download**. This downloaded file is your certificate file and it will be required in the next section. + +## grommunio configuration + +### Configure gromox JWT verification + +On the grommunio server, extract the public key from the certificate that you downloaded from authentik: + +```bash +openssl x509 -pubkey -noout -in /path/to/authentik-signing-certificate.pem > /etc/gromox/bearer_pubkey +``` + +After creating the public key file, restart gromox: + +```bash +systemctl restart gromox-http +``` + +### Create keycloak.json + +grommunio-web uses a Keycloak-compatible OIDC configuration file at `/etc/gromox/keycloak.json`: + +```json title="/etc/gromox/keycloak.json" +{ + "realm": "grommunio", + "auth-server-url": "https://grommunio.company/sso/", + "ssl-required": "external", + "resource": "", + "credentials": { + "secret": "" + } +} +``` + +### Add the nginx SSO bridge + +grommunio-web expects Keycloak-style OIDC endpoint paths under `/sso/realms/`. Add a custom nginx location file to proxy these to authentik. + +Create `/etc/grommunio-common/nginx/locations.d/sso-authentik.conf`: + +```nginx +location = /sso/realms/grommunio/protocol/openid-connect/auth { + return 302 https://authentik.company/application/o/authorize/$is_args$args; +} + +location = /sso/realms/grommunio/protocol/openid-connect/token { + proxy_pass https://authentik.company/application/o/token/; + proxy_ssl_server_name on; + proxy_set_header Host authentik.company; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; +} + +location = /sso/realms/grommunio/protocol/openid-connect/token/introspect { + proxy_pass https://authentik.company/application/o/introspect/; + proxy_ssl_server_name on; + proxy_set_header Host authentik.company; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; +} + +location = /sso/realms/grommunio/protocol/openid-connect/userinfo { + proxy_pass https://authentik.company/application/o/userinfo/; + proxy_ssl_server_name on; + proxy_set_header Host authentik.company; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; +} + +location = /sso/realms/grommunio/protocol/openid-connect/logout { + return 302 https://authentik.company/application/o//end-session/$is_args$args; +} +``` + +Then reload nginx: + +```bash +nginx -t && nginx -s reload +``` + +### Patch class.keycloak.php + +grommunio-web's OIDC client does not request the `email` or `offline_access` scopes by default. Without these scopes, grommunio cannot map the authentik user from the access token or refresh the session after login. + +Open `/usr/share/php-mapi/class.keycloak.php` and update the two scope strings from `openid` to `openid email offline_access`. + +There should be one occurrence in the authorization URL builder and one in the token request. Example diff: + +```diff +- $params['scope'] = 'openid'; ++ $params['scope'] = 'openid email offline_access'; + +- return $this->realm_url . '/protocol/openid-connect/auth?scope=openid&client_id=' . urlencode((string) $this->client_id) . '&state=' . urlencode($uuid) . '&redirect_uri=' . urlencode($redirect_url) . '&response_type=code'; ++ return $this->realm_url . '/protocol/openid-connect/auth?scope=openid%20email%20offline_access&client_id=' . urlencode((string) $this->client_id) . '&state=' . urlencode($uuid) . '&redirect_uri=' . urlencode($redirect_url) . '&response_type=code'; +``` + +After saving, reload PHP-FPM: + +```bash +systemctl reload php-fpm +``` + +## Configuration verification + +Log out of grommunio-web completely, then open grommunio-web. You should be redirected to the authentik login page. After authenticating, you will be returned to grommunio-web and logged in automatically. + +To verify single logout, click the logout button in grommunio-web. You should be redirected to the authentik session invalidation flow. + +## Resources + +- [grommunio Web Documentation](https://docs.grommunio.com/web/intro.html) +- [grommunio-web GitHub repository](https://github.com/grommunio/grommunio-web) +- [grommunio mapi-header-php KeyCloak client](https://github.com/grommunio/mapi-header-php/blob/master/class.keycloak.php) +- [Gromox authmgr bearer token verification](https://github.com/grommunio/gromox/blob/master/exch/authmgr.cpp)