Rocket.Chat and Keycloak SSO integration

The first decision is whether Rocket.Chat and Keycloak will exchange identity over SAML 2.0 or OpenID Connect. Make this choice before any configuration starts, because each protocol creates different objects in Keycloak, different values in Rocket.Chat, and different failure modes after go-live. SAML 2.0 depends on a signing certificate exchanged between the two systems and on assertion attributes that carry the user's identity and any group membership. OpenID Connect depends on a client ID, a client secret, a registered redirect URI, and claims returned in the ID token or user info response. Both work with Keycloak, so the decision is about operations and fit, not about which one is more secure in the abstract.

Certificate rotation is where the two protocols differ most in day-to-day operations. With SAML, the signing certificate that Keycloak uses for the realm or SAML client must match the certificate Rocket.Chat trusts. When that certificate is replaced, both sides must change in the same window, or every user will fail to sign in at once. With OpenID Connect, the client secret has its own rotation schedule, and a changed Rocket.Chat domain or callback path breaks the redirect URI registration. Ask your security team to record which credential expires, who owns it, and how the change is staged. Then confirm in Rocket.Chat's SSO documentation how the product stores and replaces each value for your release.

Attribute availability decides how much identity data reaches Rocket.Chat. In a SAML setup, the username, email, and any group attributes must be emitted by attribute mappers on the Keycloak SAML client, and their names must match what Rocket.Chat reads. In an OpenID Connect setup, the same information arrives as claims, which depend on requested scopes and on protocol mappers that place group or role values into the token. Rocket.Chat needs a usable email address for each account, so a missing email claim or attribute is a configuration defect, not a cosmetic one. Build a test user with known attributes and compare the raw assertion or token against the names the Rocket.Chat documentation expects.

Troubleshooting also differs. SAML failures often surface as signature validation errors, clock skew between servers, or audience and destination mismatches, and the assertion is XML that engineers must decode before they can read it. OpenID Connect failures usually appear as redirect URI mismatches, invalid client secrets, missing scopes, or claims that never reach the application, and decoded tokens are easier to inspect. Whichever protocol you choose, enable detailed logging on both Keycloak and Rocket.Chat during testing and keep a runbook for these errors.

The decision depends on two inputs. The first is what your security team already runs elsewhere, because reusing one protocol across applications simplifies certificate management, monitoring, and staff skills. The second is what the Rocket.Chat release you operate supports. Rocket.Chat's free Starter plan includes single sign-on, while LDAP and SAML user group mapping is listed on its paid plans, so confirm whether group-based access in your design requires a paid plan before you pick a protocol around it. Also check that your release is within its supported window, because unsupported versions stop receiving fixes. Confirm both points in Rocket.Chat's SSO documentation and record the answers in your design.

Single sign-on and group-based access are separate entitlements in Rocket.Chat, and only the first is included in the free Starter plan. A Keycloak login will work on Starter, but the Rocket.Chat pricing page lists LDAP and SAML user group mapping among its paid plan features. If your design depends on Keycloak groups deciding which channels, roles or workspace permissions a user receives, that depends on a paid tier. Confirm this before the claim, attribute and group design begins, because the answer changes the architecture.

Rocket.Chat's paid plans are Commercial, Government and Defense, and they are priced by quote rather than from a published list. Ask for a written quote that names each group mapping feature you need, including SAML group mapping and LDAP group mapping if you also federate a directory. Ask which tier includes each feature, whether the price covers air-gapped deployment or multi-instance designs if your user count or security rules call for them, and how the subscription renews. A quote that only says "SSO included" does not confirm group mapping.

The usual failure is planning on Starter because the SSO option is available, then finding out during testing that Keycloak groups do not place users into rooms or roles. Illustrative example: a team maps a Keycloak "finance" group expecting automatic membership in a private channel. On Starter, the admin ends up adding and removing those members by hand, so a user who leaves the finance group keeps access until someone notices. That gap usually appears late, after the Keycloak realm and clients are already built, and it is expensive to reverse.

Before design, check the current feature list on the Rocket.Chat plans page and the pricing page, since plan contents can change between releases. Record the date you checked and the Rocket.Chat version you plan to run. Then decide, for each access rule, whether Keycloak groups must drive it or whether a manual administration process is acceptable. If manual is acceptable, Starter may cover your SSO needs. If automated group mapping is required, put the paid tier into the budget and the written quote before the integration is designed.

Before any user is moved to Keycloak sign-in, run a scripted test plan that covers the account states your users will actually hit. The plan should exercise the trust between Keycloak and Rocket.Chat, not just whether the login page loads. Write each case down with the expected result in Keycloak, the expected result in Rocket.Chat, and the evidence you will keep, such as a screenshot, the Rocket.Chat user record, or the Keycloak event log entry. Start with first sign-in for a new user who exists only in Keycloak. Confirm that Rocket.Chat creates the account on first login, that the username, display name and email attributes arrive through the mappers you configured, and that the account lands in the expected default channels and roles. Then test sign-in for an existing Rocket.Chat account whose email matches a Keycloak user. Check whether your configuration links the two accounts or creates a duplicate, because a mismatched or unverified email is the most common cause of a second account appearing.

Next, test the negative cases. Disable a test user in Keycloak and attempt sign-in to Rocket.Chat, then confirm that the session fails and that the user cannot reach the workspace through a cached token or the mobile and desktop clients. Remove a test user from a group or realm role that your Rocket.Chat role mapping depends on, then sign in again and confirm the Rocket.Chat role or group membership changes as your design intends. If group and role mapping depends on a paid Rocket.Chat plan, confirm that your edition supports it before you rely on the result of this case. Test logout from both directions. Sign out of Rocket.Chat and confirm whether the Keycloak session also ends, then sign out of Keycloak and confirm that Rocket.Chat no longer accepts the old session. Record the results separately, because Rocket.Chat and Keycloak can each keep their own session lifetimes. Confirm the token and session timeouts with your team rather than assuming defaults.

Keep these tests in a non-production Keycloak realm and a non-production Rocket.Chat workspace where possible, so that disabling accounts, changing groups and forcing logouts does not disturb real users. Test accounts should mirror the attributes, groups and roles of production accounts. Where you cannot run a separate workspace, use dedicated test identities and document exactly which production objects you touched and how you restored them. Failover of Keycloak is a separate exercise. Keycloak's high availability designs depend on a synchronously replicated database, and the failover tests for that database, the cluster and any availability zone behavior belong to the Keycloak infrastructure plan. Passing the sign-in tests above does not prove that Rocket.Chat keeps working when a Keycloak node or zone fails. Plan a second test window for that, and confirm with your database and platform owners how replication and failover are verified in your environment.

Agree on pass criteria, the owner for each case and the rollback steps before the test window opens. A cutover should not proceed while any negative case, such as a disabled account that can still sign in, is unresolved. Ask your implementation partner to show the test script, the evidence format and the list of environments they used, so that the same plan can be repeated after any Keycloak or Rocket.Chat upgrade.