Intercom-Service Integration Architecture
The intercom-service is a small but critical piece of openEDU infrastructure. It is a browser-side proxy and broker that enables cross-application communication — file pickers, video-conference room creation, silent single sign-on between apps, and portal navigation. By holding the user's OpenID Connect session and exposing it to the rest of the suite through a trusted intermediary, it makes a diverse catalog of separately deployed services behave like one cohesive workspace.
What the Intercom-Service Is
The intercom-service is a lightweight proxy that runs inside the user's browser context. Each participating application embeds the intercom-service as an iframe and communicates with it over postMessage. Because the iframe lives on the intercom-service origin, it can hold credentials and session state that the individual applications cannot directly share — the iframe acts as a trusted broker on the user's behalf.
This design keeps the intercom-service deliberately thin. It does not store application data; it brokers navigation, session, and cross-app intent between applications that are otherwise isolated by the browser's same-origin policy.
The Capabilities It Provides
Across the suite, applications rely on the intercom-service for a shared set of browser-level capabilities:
- Silent login — passing OpenID Connect tokens between applications without a user-visible re-authentication step.
- Portal navigation — fetching the central navigation structure so every application renders the same portal menu.
- File picking — opening a file from the suite's file-storage service inside another application.
- Video-conference rooms — creating conference rooms from within a collaborating application.
- Backchannel logout — coordinating session termination across all applications so a single logout ends every session.
These capabilities are the glue that makes a multi-service platform feel integrated rather than a collection of unrelated websites.
Integration with the Identity Layer
Authentication is centralized on Keycloak, which serves as the suite's OpenID Connect provider. The intercom-service participates in this realm through its own OIDC client, configured for the platform's claim naming (the opendesk_username claim). Because the intercom-service holds the OIDC session, it can perform a silent login on behalf of a child application: the application redirects to the intercom-service, the broker exchanges the stored session for tokens, and the application continues without prompting the user.
By default the OIDC client is provisioned through the suite's Keycloak bootstrap process, so its claims are controlled centrally and consistently with the rest of the platform. Backchannel logout is coordinated through the same OIDC flow, so terminating a session in one place propagates to every application that relies on the broker.
What the Intercom-Service Brokers
The intercom-service is configured with the set of trusted applications it brokers, and the suite enables exactly the integrations each deployment needs. In the openEDU platform these include:
- File storage — the Nextcloud and OpenCloud file services, enabling cross-application file picking and silent access.
- Groupware — the OX App Suite groupware backend, with optional support for the Grommunio groupware stack where enabled.
- Wiki — the XWiki service.
- Communication — the Matrix (Synapse) deployment, wired for messaging and video, with the intercom-service configured for the Matrix server and its application-service hook.
The platform treats the broker's backend list as opt-in: a deployment enables the integrations it actually runs, so the intercom-service always reflects the concrete service selection of the instance rather than a fixed catalog. This mirrors the platform's modular design, where every service can be enabled or disabled independently.
How Applications Consume the Broker
Applications join the broker by embedding the intercom-service iframe and pointing it at the broker's endpoints. In practice:
- Chat (Element) is configured with the intercom-service's navigation and silent-login URLs, so the messaging client renders the shared portal and logs in silently alongside the rest of the suite.
- Notes uses the broker's base URL as its integration endpoint for cross-application session and navigation behavior.
The pattern is consistent: an application declares a small set of integration URLs pointing at the intercom-service, and the broker handles the shared session and navigation concerns on its behalf. No application needs its own federation or session logic.
Deployment Pattern
The intercom-service runs as a Kubernetes workload managed through the platform's Helm/helmfile configuration, alongside the other services in the suite:
- It is packaged as a standard container image on a lightweight Alpine base rather than requiring a service-specific system image, so it deploys on any Kubernetes cluster without platform-specific dependencies.
- It runs hardened — non-root, read-only root filesystem, dropped Linux capabilities, and a restricted seccomp profile, consistent with the security posture of the rest of the suite.
- It exposes a health endpoint for Kubernetes liveness and readiness probes.
- Its session state is held in the platform's shared Redis-backed cache layer.
- It runs behind the platform's ingress, protected by the same TLS and ingress configuration as every other service.
Because it holds session state and brokers tokens, the intercom-service is treated as a security-sensitive component: it is provisioned with the same hardening and certificate handling as the suite's identity-related services.
Relationship to Upstream
The intercom-service is maintained upstream by the openEDU CE project and packaged for the unified collaboration environment. openEDU deploys the same intercom-service and configures it for the education platform's claim naming and backend selection. The platform's extension of the broker for the education stack — adding file-storage support beyond the community edition and configuring the groupware, wiki, and communication backends for its deployment — is documented in the community post Extending the Intercom-Service.
Further Reading
- System Architecture Overview — the full platform architecture
- Identity & Authentication Architecture — how OIDC and SAML federation are handled
- Security Architecture — how session and identity data is protected
- Extending the Intercom-Service — the community post on brokered integrations and governance
The intercom-service is what makes a catalog of independently deployed services behave like a single workspace — a small broker carrying a large share of the platform's integration load.
