grommunio 2026.06.2 Upgrade and Technical Acceptance: Keycloak SSO, MFA, AutoDiscover and Mail Flow

Introduction

From an operations perspective, grommunio 2026.06.2 is not just a package update. The interesting part begins where existing components have to work again as one platform after the upgrade: Web, Files, Chat, Archive, Admin and central sign-in through grommunio Auth and Keycloak.

For that reason, this article is structured as a practical upgrade guide: what to record before the upgrade, how to document the move from 2026.06.1 to 2026.06.2, which SSO/Keycloak points needed follow-up work, and which tests belong into acceptance afterwards. The core message is simple: a successful package update is not a fully verified platform upgrade.

Test Environment and Assumptions

• Date: October 2, 2026.

• Environment: isolated test appliance with grommunio 2026.06.1 as the starting point.

• Upgrade path: grommunio 2026.06.1 to grommunio 2026.06.2.

• No production system: test host, test domain and reproducible starting state.

• Goal: validate upgrade, central Keycloak SSO flows and operational health in a way that becomes a useful admin checklist.

Upgrade Runbook

The safe procedure consists of three phases: record the pre-upgrade state in a provable way, execute the upgrade in a controlled manner, and then verify not only services, but real user and client flows.

1. Check snapshot or backup and know the restore path.

2. Record package versions, active services, SSO baseline and central endpoints.

3. Check the official upgrade path for the installed appliance version.

4. Run the upgrade and preserve the complete output.

5. Take reboot recommendations seriously and reboot in a controlled way.

6. After reboot, check systemctl --failed and zypper ps -s.

7. Verify Files, Chat, Archive, Admin and Keycloak through login flows, not only as services.

8. Check Autodiscover, Autoconfig, SMTP, IMAP, DAV, ActiveSync and EWS at least at endpoint level.

9. Document findings explicitly as PASS, FAIL, SKIPPED, NOT TESTED or NOT APPLICABLE.

What Mattered Most When Upgrading from 2026.06.1 to 2026.06.2

Before the Upgrade: Establish a Baseline

Without a baseline, an upgrade test quickly loses value. If something breaks afterwards, you need to know whether the issue is new or already existed. Before the upgrade, package versions, services, relevant endpoints and the existing SSO state should therefore be recorded.

rpm -qa | sort | grep -E '^(grommunio|gromox)'
systemctl --failed
zypper ps -s
openssl s_client -connect mail.example.test:443 -servername mail.example.test -verify_return_error
curl --fail https://mail.example.test/web/
curl --fail https://mail.example.test/files/status.php
curl --fail https://mail.example.test/auth/realms/grommunio/.well-known/openid-configuration

Upgrade to 2026.06.2

The actual package update can be documented differently depending on appliance state and vendor recommendation. In the validated environment, the grommunio-update helper was also present, while the checked operations documentation still describes package updates through zypper ref and zypper up. For runbooks, both belong into the check: the official upgrade path for the installed version and the commands that were actually executed.

zypper --non-interactive --gpg-auto-import-keys ref
zypper --non-interactive --gpg-auto-import-keys up

# Nach dem Reboot:
zypper ps -s
systemctl --failed

For a production guide, the exact command is not the only relevant point. What matters is that the selected upgrade path matches the appliance version, that the output is preserved, and that functional acceptance follows afterwards. A runbook should therefore always include the tests below in addition to the package command.

Paket                         Version nach dem Upgrade
grommunio-release             2026.06.2
grommunio-web                 5.1.20
grommunio-files               34.0.4
grommunio-keycloak            26.7.4
grommunio-auth                0.2.37
gromox                        3.11.136
grommunio-admin-api           1.21.23
grommunio-chat-v10            10.5.8
grommunio-archive             1.4.9

How Completely Did We Test the Appliance?

The final acceptance run was built close to production behaviour: not just 127.0.0.1, but the real lab FQDN mail.example.test with SNI, hostname verification and an explicitly trusted lab certificate. The report clearly separates real PASS results from areas that were not tested or not applicable.

For partners and customers, this produces a usable runbook: baseline first, then verify the upgrade path, run the update, then check system health, Files, Keycloak/OIDC, browser SSO, mail flow, Autodiscover, Autoconfig, DAV, EWS and EAS. Clients such as Thunderbird, Outlook or ActiveSync only count as PASS when they have actually been run with a fresh profile or controlled test client.

Technical Acceptance

Acceptance follows the unified grommunio format. PASS means that the specific check was actively executed and evidenced. FAIL, SKIPPED and NOT TESTED remain visible deliberately so that a package update does not create false assurance.

Mandatory Tests After the Upgrade

The following list is the core of acceptance. A grommunio upgrade should only be considered complete when these points either pass or are deliberately documented as not tested.

• System: package state, failed units, reboot state, central services.

• Identity: Keycloak realm, OIDC discovery, clients, redirect URIs, callback behaviour.

• MFA: required actions, TOTP setup, Admin access only after MFA.

• Web: login, reload, mailbox visible, no authentication errors.

• Files: occ status, needsDbUpgrade false, server-side OIDC discovery, Files UI.

• Chat: SSO login, user mapping, channel view.

• Archive: SSO login, search interface, no OIDC errors.

• Admin: SSO button, preferred_username mapping, role, dashboard.

• Mail: SMTP Submission, STARTTLS, AUTH, IMAP delivery.

• Discovery: Autodiscover and Autoconfig for clients.

• Protocols: DAV via PROPFIND, EWS via a real SOAP request, ActiveSync at least with the expected auth challenge and then with a real client if used in production.

• Meet: check web route and Jitsi backend services separately.

• Negative tests: wrong password must not create an application session.

• Logout/session: treat local logout and Keycloak session behaviour separately.

What Does PASS Mean in This Test?

For browser SSO, PASS does not simply mean HTTP 200. A flow was only counted as successful when the application was opened, the redirect went to the correct identity provider, authentication worked, required MFA steps completed, the OIDC callback returned, an application session was created and a clearly authenticated UI element became visible.

For native protocols, PASS is defined more narrowly: SMTP/IMAP was tested as a delivery mail flow, DAV with authenticated PROPFIND and EWS with a real SOAP GetFolder request against the Inbox. ActiveSync was additionally tested with a controlled client for provisioning, FolderSync and initial Sync. A real iOS or Android device with customer policy and push behaviour remains a separate mandatory step when those exact devices are used in production.

Client and MFA Matrix

Central browser sign-in and native clients must be evaluated separately. Keycloak, OIDC and MFA protect the web and browser flows. IMAP, SMTP, DAV, EWS and ActiveSync may use different authentication paths depending on client and configuration. A successful browser MFA test must therefore not automatically be counted as Thunderbird, Outlook or mobile-sync acceptance.

Thunderbird and Real Devices as the Final Acceptance Step

For customers using Thunderbird in production, acceptance does not end with XML. The client path was therefore re-tested with Thunderbird 156.0 and a fresh profile: IMAP/SMTP account, inbox, SMTP submission with attachment and IMAP delivery verification. The deeper native-client acceptance is documented as a dedicated follow-up article: /en/tech/grommunio-native-clients-after-keycloak-sso.

Calendar and contact CRUD through CalDAV/CardDAV as well as a full EWS GUI path are deliberately not counted as full Thunderbird PASS. These points belong in separate client tests when they matter in a customer environment.

For ActiveSync, the client step was added: a controlled EAS test client successfully completed connectivity, provisioning, FolderSync with 14 folders and an initial Sync across 11 collections. This is solid server and protocol evidence. It does not replace a customer-specific iOS or Android test with real policies, push behaviour, device management and user workflows.

First Pitfall: Files Returned HTTP 503

After the package update, grommunio Files was not fully operational at first. The application returned HTTP 503 even though the package update itself had succeeded. The cause was not a global platform outage, but a pending Files database upgrade.

sudo -u grofiles php -d memory_limit=1024M /usr/share/grommunio-files/occ upgrade

That is an important operations lesson: a successful package update does not automatically mean that all database-backed components are already running on the new schema. After an upgrade, Files should be checked with occ status, logs and an actual login.

Central Authentication with grommunio Auth and Keycloak

The stronger centralisation of sign-in is the real focus of this test. grommunio Auth provides the Keycloak integration, the individual applications use their own OIDC clients or adapters, and Keycloak becomes the central point for login, required actions and MFA.

Keycloak
                         |
                    grommunio Auth
                         |
         +---------------+----------------+
         |               |                |
         v               v                v
        Web            Files            Admin
         |               |                |
         +-------+-------+-------+--------+
                 |               |
                 v               v
                Chat           Archive

Meet is considered separately on purpose: the /meet/ web route returned HTTP 200 in the final endpoint test, and the relevant services jitsi-jicofo, jitsi-videobridge and prosody were active. For customer release, an additional two-browser or two-client room test should be performed because a reachable frontend alone is not full media-path acceptance.

Which SSO Flows Actually Worked

Component        Result         Notable point
Web              successful     Keycloak login into the web UI
Files            successful     DB upgrade, TLS trust and callback validated
Chat             successful     existing accounts migrated to SSO
Archive          successful     adapter configuration added
Admin            successful     preferred_username mapping plus MFA through to dashboard

SSO Login Evidence per Module

For acceptance, showing only a final dashboard is not enough. Each module needs visible evidence of how SSO starts: direct redirect to Keycloak or local login page with a Keycloak button. The following screenshots show exactly that entry point for each application.

https://mail.example.test/auth/realms/grommunio/

Screenshot: Web: unauthenticated access redirects directly to the Keycloak login form.

https://mail.example.test/files/

Screenshot: Files: the local login page offers entry through grommunio Keycloak.

https://mail.example.test/auth/realms/grommunio/

Screenshot: Files: after clicking grommunio Keycloak, the central Keycloak login form opens.

https://mail.example.test/chat/login

Screenshot: Chat: the login page shows the Keycloak entry next to local login.

https://mail.example.test/auth/realms/grommunio/

Screenshot: Chat: after selecting Keycloak, the browser lands in the central realm.

https://mail.example.test/auth/realms/grommunio/

Screenshot: Archive: unauthenticated access opens the Keycloak login form.

https://mail.example.test/web/

Screenshot: grommunio Web is reachable after Keycloak login with a test mailbox.

https://mail.example.test/files/

Screenshot: grommunio Files loads after OIDC callback and completed Files database upgrade.

https://mail.example.test/chat/login

Screenshot: grommunio Chat reaches an authenticated channel view after SSO.

https://mail.example.test:8443/login

Screenshot: The Admin login offers the SSO entry point after the upgrade.

https://mail.example.test/auth/realms/grommunio/

Screenshot: After clicking SSO, the browser lands at Keycloak in the grommunio realm.

https://mail.example.test:8443/

Screenshot: After authentication and MFA setup, the grommunio Admin dashboard is reachable.

Chat: Move Existing Accounts to SSO

Chat matters especially in existing installations because existing accounts do not automatically mean that the new login path is already used cleanly. Existing Chat accounts should therefore be checked for SSO explicitly and migrated if required.

grommunio-admin chat sso enable

Afterwards, the Chat service, login button and channel view belong in the acceptance test.

Archive and Admin: Add Missing Adapters

In existing environments, check after the upgrade whether the adapter configuration for Archive and Admin is actually present. If it is missing or does not match the realm, it must be added explicitly. This is not a blanket grommunio Auth defect, but a useful upgrade control point.

/usr/share/grommunio-auth/setup-grommunio-auth-clients.sh archive admin

The important distinction is this: what does the vendor provide, what should happen automatically, and what actually happened in a specific environment? That distinction makes an upgrade test useful.

Files: TLS and OIDC Discovery

Files needs OpenID provider metadata not only in the browser, but also server-side. If internal or self-signed certificates are used, the OS trust store and the Files environment must trust that CA.

In a properly built production PKI, this special case should normally not appear. The architecture lesson still matters: OIDC is not just browser communication; it also affects server-side discovery and TLS trust.

Pitfall: OIDC Callback and PATH_INFO

The Files OIDC callback under /files/index.php/apps/user_oidc/... is a good candidate for upgrade issues when nginx, PHP-FPM or rewrite rules were customized. Rather than publishing a full Nginx configuration, the checklist matters more.

• Does the browser return from Keycloak to the expected callback URL?

• Is index.php recognised as the script and the remaining path passed as PATH_INFO?

• Does PHP-FPM see the same path that Nginx sees?

• Does the callback return 403, 404 or 500 instead of an application session?

• Were the Nginx error log, PHP-FPM log and Files log checked for the same timestamp?

Admin SSO: Identity Mapping Matters More Than the Password

One particularly important finding concerns grommunio Admin. The Admin API resolves the OIDC claim preferred_username against the grommunio Admin user database. A local admin password alone therefore does not make SSO work.

Keycloak
   |
   | preferred_username
   v
grommunio Admin API
   |
   | User lookup
   v
grommunio Admin Database

• Which federated identity receives admin access?

• Which username is transmitted as preferred_username?

• Is there a matching grommunio Admin user?

• Which role does that user have?

• Should the local admin account be used for SSO at all?

• Which MFA policy applies to admin access?

MFA Tested Through to the Dashboard

The Admin test was not a superficial button test. The browser was sent from Admin to Keycloak, Keycloak enforced the required action for TOTP, MFA setup was completed, and only then did the browser return to the Admin dashboard. That is what a secure flow should look like.

1. Select Admin SSO.

2. Redirect to Keycloak.

3. Authenticate.

4. Complete TOTP setup as a required action.

5. Verify MFA.

6. Return to the grommunio Admin dashboard.

Why Browser SSO Must Be Tested Properly

An HTTP 200 says little about whether an identity flow works. SSO consists of redirects, cookies, OIDC callbacks, application sessions, MFA required actions and UI state. That is why acceptance should always be performed as a real browser flow.

Application
    ↓
Redirect
    ↓
Keycloak
    ↓
Authentication
    ↓
MFA / Required Actions
    ↓
OIDC Callback
    ↓
Application Session
    ↓
Authenticated UI

For reliable acceptance, the browser run should be logged: opened application, redirect target, callback, visible login state and errors from the browser console or server logs. This makes it clear whether Web, Files, Chat, Archive and Admin really work through SSO.

One Login, Multiple Applications

SSO does not necessarily mean that every application immediately has its own session without any redirect. In practice, the flow can still pass through Keycloak while reusing the existing identity session. This behaviour was measured separately in one shared browser context.

Switch in the same browser context       Observation
Web login                                successful as alice@example.test
Web -> Archive                           transparent Keycloak session reuse
Web -> Files                             Files showed its own login/SSO entry
Web -> Chat                              Chat showed its own login/SSO entry
Web -> Admin                             not tested in the same user context

https://mail.example.test/files/

Screenshot: Cross-app test: Files still showed its own login with Keycloak button on direct entry.

This is not a contradiction to SSO, but an important acceptance finding: some applications start the OIDC flow transparently, while others first expect the explicit SSO entry inside the application.

Autodiscover Belongs in Acceptance Testing

A groupware platform is more than web interfaces. After the upgrade, Autodiscover, Mozilla Autoconfig and central protocol paths were checked as well. Autodiscover V1 and V2 returned usable responses, Autoconfig returned XML with IMAP and SMTP information, DAV answered an authenticated request with 207 Multi-Status, EWS answered a SOAP GetFolder request against the Inbox with HTTP 200, and ActiveSync was tested through provisioning, FolderSync and initial Sync.

Mail Flow and Protocols

SMTP Submission with STARTTLS, authentication and local delivery into a test mailbox was also checked. IMAPS verified that the message arrived in the inbox. Webmail sending, reply and Sent Items remain separate browser tests; ActiveSync FolderSync was tested with a controlled client, while real mobile devices remain a separate acceptance step when used in production.

Final Health Check

• No failed systemd units.

• zypper ps -s reported that no reboot was required anymore.

• Keycloak active.

• Admin API active.

• Nginx active.

• PHP-FPM active.

• MariaDB active.

• Redis active.

• Gromox active.

• Chat active.

• Archive active.

• Meet web route reachable, jitsi-jicofo, jitsi-videobridge and prosody active.

Upgrade Checklist

1. Record package versions, services, endpoints and SSO baseline before the upgrade.

2. Check the official upgrade path for the installed appliance version; also verify whether grommunio-update is present and which package commands the vendor documentation describes for exactly this version.

3. Run the package upgrade and take reboot requirements seriously.

4. After reboot, check zypper ps -s and systemctl --failed.

5. Check Files with occ status and run occ upgrade if required.

6. Migrate Chat accounts to SSO when existing accounts are present.

7. Verify grommunio-auth adapters for all relevant applications.

8. Validate TLS trust for server-side OIDC discovery.

9. Check OIDC callbacks in the browser and logs.

10. Define Admin identity mapping through preferred_username deliberately.

11. Test MFA for admin access all the way to the dashboard.

12. Document browser smoke tests for Web, Files, Chat, Archive and Admin.

13. Test native protocols with the real FQDN, valid trust chain and synthetic test data.

14. Only count desktop and mobile clients as PASS when a fresh profile or real test client was configured.

Partner Runbook: Order for Your Own Environments

When using this article as a template for customer environments, run the steps in this order. Lab values such as mail.example.test are placeholders and must be replaced by the real FQDN, real mail domain and production or enterprise CA.

FAQ

Is zypper up enough as an upgrade test?

No. zypper validates packages, but not whether Files database migration, OIDC discovery, callback, MFA and application sessions work.

Should grommunio-update be used?

The tested appliance provides grommunio-update with check, update and upgrade actions. At the same time, the currently checked grommunio Operations documentation describes package updates through zypper ref and zypper up. For runbooks, that means: do not guess; check both the vendor documentation and the installed tool for the specific version.

Was MFA an Admin login problem?

No. When Keycloak enforces a TOTP required action, that is expected security behaviour. The important part is to test the flow through completed MFA setup and back into the Admin dashboard.

Does everyone need to run these manual steps?

Not as a blanket rule. The article separates vendor behaviour, expected automation, possible follow-up work in existing environments and environment-specific special cases. That is exactly why upgrades should be tested reproducibly before production.

Conclusion

An upgrade to grommunio 2026.06.2 only becomes meaningful after full technical acceptance. The decisive parts are not only packages and services, but database migrations, identity configuration, TLS trust, callback behaviour, MFA and real browser flows.

For production environments, that is the difference between an update and a reliable platform upgrade.