How authentik SSO sign-in works for Rocket.Chat
Teams running self-hosted Rocket.Chat often want staff to sign in with the same central identity they use everywhere else. The supported approach is to configure authentik as an OAuth2/OpenID provider wired into Rocket.Chat's custom OAuth login, as listed in the authentik integrations catalog. In practice, a user chooses the login option in Rocket.Chat, authenticates against authentik, and is returned to Rocket.Chat with an identity token that the server uses to match or create a Rocket.Chat account. The authentik Rocket.Chat guide in the authentik integrations catalog is the right starting reference for the provider and application setup on the authentik side.
The integration changes how users prove who they are, but it does not replace Rocket.Chat's own account model. Rocket.Chat still stores users, roles, rooms, messages and workspace settings in its own database, and an OAuth login creates or links a local user record. Existing local accounts are not automatically reassigned to the central identity, so the team must decide how current users are matched, which claim serves as the username, and whether a password fallback remains for administrators. Those decisions shape the rest of the work, and they are easier to settle before the first pilot login than after staff have accumulated messages under the old accounts.
Before you change production settings, confirm with your authentik and Rocket.Chat versions that the custom OAuth fields described in the guide still match your release, and test the full path with a non-administrator account in a staging workspace. Plan for the login button and callback URL to depend on the exact public address of your Rocket.Chat server, so a hostname change later will break sign-in until the authentik provider is updated. Record who owns each side of the configuration, because a lockout on either side can leave the workspace without an administrator who can sign in.
What you need in place before configuring the integration
Three running parts have to be in place before any OAuth settings are entered: an authentik deployment that issues tokens, a Rocket.Chat instance on a supported release line, and a Rocket.Chat plan that includes single sign-on. The cards below cover each part, the database requirements behind them, and the version checks to complete before work starts.
A working authentik deployment
Rocket.Chat only needs authentik to act as an OAuth2/OpenID provider, so the authentik side must be reachable over HTTPS from both users' browsers and the Rocket.Chat server. For a small test or small-scale production setup, Docker Compose is the documented route, and the guide lists at least 2 CPU cores and 2 GB of RAM. For production, the Helm route is the better fit, but the PostgreSQL bundled with the chart is meant for demonstration and testing, so plan a separately managed PostgreSQL before go-live.
A supported authentik release line
Pick an authentik version from the lines that still receive security fixes, then confirm it against the security policy and the releases page before you install. Upgrades must follow the sequence the project documents, so the version you deploy today shapes your upgrade path later. Record the exact version and the URL of the Rocket.Chat callback you will register, because a mismatch between them is a common cause of failed logins.
A supported Rocket.Chat release line
Rocket.Chat standard releases are supported for 6 months and LTS releases for 12 months. After end of life, a version gets no security or bug fixes, and some cloud services stop working. Choose a current standard or LTS line and check the version durability page for its end-of-life date, because the custom OAuth settings you configure now must survive the next upgrade. Confirm the latest patch on the releases page at the time of the change.
A plan that includes SSO
Custom OAuth login in Rocket.Chat is tied to the plan you run. The free Starter plan includes single sign-on and LDAP, but the Community workspace does not list the same identity features, so confirm the plan in the plans documentation before you plan the change. Commercial, Government and Defense plans are priced by quote, so ask the vendor to confirm in writing which plan covers SSO and any group mapping you intend to use.
MongoDB 8.0 or later as a replica set
Rocket.Chat 8.x requires MongoDB 8.0 or later running as a replica set, so a standalone database will not work. A three-member replica set is strongly recommended for high availability. Confirm the database version and replica set state on the system requirements page before you upgrade Rocket.Chat, because a database that is not ready will block the upgrade and leave login settings unverified.
Callback URLs and hostnames
The OAuth redirect URL in authentik must match the Rocket.Chat server URL exactly, including scheme, hostname and port. Decide the public hostname for both services before you create the provider, because changing it later means updating the authentik provider, the Rocket.Chat settings and any client redirect that was saved. Confirm the exact callback path against the authentik integration guide for Rocket.Chat before you register it.
Configuring authentik and Rocket.Chat in sequence
This sequence produces a working OAuth login from Rocket.Chat to authentik, with a verified redirect, the expected identity claims and a test account that signs in without administrator rights. Each step ends with a check so problems surface before users are asked to sign in.
Confirm the public Rocket.Chat address
Before touching either product, decide the final public URL users will type into their browser, including the scheme, host and any port. The redirect URI you register in authentik must match this address exactly, so the value is fixed here and reused in every later step. Record it in your change notes. Done means the address is written down, reachable over HTTPS from a user network, and agreed by the people who own DNS and the reverse proxy.
Create the OAuth2/OpenID provider in authentik
In the authentik admin interface, create an OAuth2/OpenID provider and an application that uses it, and set the redirect URI to the callback path shown on the authentik integrations page for Rocket.Chat, built on the address from the previous step. Take the exact field names and callback path from that integrations page and from authentik's current provider form, not from memory, because labels change between releases. Done means the provider saves and the redirect URI in authentik matches your Rocket.Chat address character for character.
Record client ID, secret and issuer
Copy the client ID, the client secret and the OpenID issuer URL from the authentik provider page into a secure store, such as your secrets manager. The issuer URL is the one authentik publishes for the application, and it is the value Rocket.Chat will use to discover the provider's endpoints. Do not paste the secret into tickets or chat. Done means all three values are stored, and you can open the issuer URL in a browser and see the provider's discovery document.
Check the claims in the provider preview
Before configuring Rocket.Chat, use authentik's preview for a test user to see which claims the provider returns, particularly the username, email and any group claims you plan to use. Rocket.Chat maps fields from these claims, so a missing or differently named claim will cause login or account matching to fail later. Note the exact claim names and any scope you need to request. Done means you have a written list of claim names from a real test user, not from documentation alone.
Enter custom OAuth settings in Rocket.Chat
As a Rocket.Chat administrator, open the administration settings for OAuth and add a custom OAuth provider. Enter the client ID, secret, authorization, token and identity endpoints taken from authentik, along with the scope and the claim field names you recorded. Take each label and option from the Rocket.Chat admin screens for your version, since names differ across releases. Done means the settings save without validation errors and the custom login button appears on the Rocket.Chat sign-in page.
Test sign-in with a non-admin account
Sign out, open the Rocket.Chat login page in a private browser window, and sign in through the new button with a standard user account that has no administrator role. Confirm that authentik prompts for credentials, returns to Rocket.Chat, and creates or matches a user with the expected username and email. Done means a non-admin user reaches the workspace through authentik, and the username and email shown in the profile match the claims you recorded.
Review logs for failed token exchanges
If the test fails, check the Rocket.Chat server logs for the failed step, and compare the error with the authentik event log for the same attempt. A redirect URI mismatch, a wrong secret or a missing claim usually shows up at a different point in the flow, so match the timestamp in both places. Correct the setting, then repeat the test from a clean browser session. Done means a test login succeeds without errors in either log, and you have recorded the final settings for the change record.
Which authentik claims map to Rocket.Chat user fields
This table lists the identity values Rocket.Chat needs at login (username, email, display name, and group or role data), where each value originates in authentik, and what to confirm in the authentik integration guide and your Rocket.Chat settings. Use it as a checklist before the first test login, because a wrong claim choice is the most common cause of duplicate or mismatched accounts.
| Identity field | authentik source | Rocket.Chat field and what to confirm |
|---|---|---|
| Username | The user's username attribute on the authentik user object, returned through the OAuth2/OIDC provider's identity claims | Rocket.Chat username. Confirm the claim name and whether it is the username Rocket.Chat should use for mentions and login in the authentik integration guide |
| Email address | The user's email attribute, released only when the email scope is requested by the application | Rocket.Chat email and the key used to match existing accounts. Confirm the scope name, and whether authentik marks the address as verified in your configuration |
| Email verified status | Verification state of the email address in authentik, if your flows enforce email confirmation | Rocket.Chat may trust or ignore this flag depending on settings. Confirm in Rocket.Chat's custom OAuth documentation how it treats an unverified address |
| Display name | The user's name attribute on the authentik user object, typically released through the profile scope | Rocket.Chat display name. Confirm the claim name and whether the name is overwritten on each login or only set at account creation |
| Groups or roles | Group membership on the authentik user, released only if a scope mapping includes it in the token or userinfo response | Rocket.Chat roles through role mapping settings. Confirm the claim name, the scope needed to release it, and how group names must be spelled to match Rocket.Chat roles |
| Changed email or username on next login | The value currently stored on the authentik user, which Rocket.Chat receives at each sign-in | Rocket.Chat behavior varies by setting. Test a change in a non-production instance and confirm whether the account is matched by email, by identifier, or created as a new user |
| Unique subject identifier | The subject (sub) claim authentik issues for the user, which stays stable even if names change | Confirm in the Rocket.Chat guide whether the subject or the email is used as the account key, because this decides how existing local accounts are merged |
What happens to users who already have Rocket.Chat accounts
The main risk when adding authentik to a Rocket.Chat workspace that already has users is duplicate or mismatched accounts. A user who signs in through the new OAuth provider may be matched to an existing local account, or may get a new one, depending on which claim Rocket.Chat uses to identify them. If the username claim from authentik differs from the username already stored in Rocket.Chat (for example, a different casing, a dotted form, or a nickname), the user can end up with a second account that holds none of their history, channels or roles. Email is the other lever, and it fails in a different way: two local accounts that share an address, or an address that changed at the identity provider, can produce a match to the wrong record or a conflict at login.
Before cutover, export the current user list and review it against the claims authentik will send. Compare usernames and email addresses in the export with the values for the same people in authentik, and flag mismatches, duplicates, bot and integration accounts, and deactivated users. Choose one matching key (usually the email address if it is unique and verified, or the username if your naming policy is enforced at both ends) and write down what happens when that key is missing or ambiguous. Then test with a sample of existing users, including an administrator, a user with a changed name and a user with a shared address, in a non-production copy of the workspace. Confirm the outcome in the exact Rocket.Chat version you run, because merge and linking behavior for OAuth logins is version-dependent and should be verified in your own environment rather than assumed from this page.
Plan the accounts that will have no matching identity before users are told to switch. Typical options are to leave local logins active for a defined transition period, to deactivate and archive accounts that belong to people who have left, and to route exceptions to an administrator who can link or rename accounts by hand. Decide who owns each exception, how long the transition window lasts, and how users will be told which address and username to use. Keep the export and the test results with the change record, so you can show what was matched, what was created and what was left alone if a user reports missing history after go-live.
How role and group mapping differs by Rocket.Chat plan
The free Starter plan includes single sign-on and LDAP or Active Directory authentication, and it allows up to 50 users. Sign-in through authentik can work on this plan, but the plan facts supplied for this topic do not list LDAP or SAML user group mapping among its features. Plan your access model around what the first login establishes, and treat any group-driven role changes as something to verify in your own instance before relying on them.
- Confirm the plan features first: Check the current Starter entitlements in the Rocket.Chat plans documentation against the version you run, since feature lists change between releases.
- Keep the first login unprivileged: Create new users with standard roles so that a claim or default setting cannot grant administrator rights on first sign-in.
- Assign admin rights by hand: Grant administrator and moderator roles through a documented, named process after the account exists, and record who approved each change.
- Plan for the 50-user limit: If your population is larger, the Starter plan will not fit, and the paid plan decision affects role design.
- Test with a non-production account: Sign in with a test user from authentik and confirm the role and username that Rocket.Chat assigns.
Before cutover, confirm in writing which role changes, if any, the Starter plan applies from authentik claims.
The paid plans (Commercial, Government and Defense) list LDAP and SAML user group mapping, which lets Rocket.Chat use directory group membership to shape access. Whether a group or claim from authentik maps to a Rocket.Chat role depends on the mapping method, the Rocket.Chat version and the plan in use. Confirm the exact configuration path and behavior for your version with Rocket.Chat before you rely on it, because the authentik integration guide describes the OAuth setup rather than group-to-role mapping inside Rocket.Chat.
- Choose one source of truth for roles: Decide whether roles come from authentik groups, from Rocket.Chat's own administration, or from a combination, and document the rule.
- Map groups to a small set of roles: Use a few clearly named groups in authentik, such as messaging users and messaging administrators, and avoid mapping broad groups to privileged roles.
- Require a second approval for privileged roles: Keep administrator assignment outside automatic group sync, or require a reviewed change in authentik before the group is granted.
- Review role changes after cutover: Compare Rocket.Chat role assignments with authentik group membership at a fixed interval and after each identity change, and log the results.
- Check the audit trail: Confirm that role changes appear in the audit records your plan provides, so reviewers can trace who changed what and when.
Before relying on group mapping, ask Rocket.Chat to confirm the mapping behavior for your exact version and plan.
Security settings to lock down in this integration
Five controls decide how exposed this integration is once users sign in through authentik. Each one sits on a different layer: the OAuth client, the redirect configuration, the authentik application binding, the Rocket.Chat login settings and the version you run. Check all five before you announce SSO to users.
Client secret storage and rotation
The OAuth client secret lets Rocket.Chat exchange authorization codes for tokens, so anyone who holds it can impersonate the application. Store it in your secrets manager or a restricted environment file on the Rocket.Chat host, not in shared chat or ticket text, and limit read access to the people who run the server. Confirm in authentik which provider holds the secret, record who can view it, and plan a rotation step that updates authentik and Rocket.Chat together so sign-in does not break mid-change.
Exact redirect URI matching over HTTPS
Register the callback URL that Rocket.Chat generates for your exact public hostname, using HTTPS only. Avoid wildcards, trailing-slash variants, and redirect URIs that point at test or old hostnames, because a loose match lets an attacker steer an authorization response to another location. Confirm the hostname in Rocket.Chat's site URL setting matches the one in authentik, and recheck both after any domain change or reverse proxy move.
Restricting access by authentik group
Bind the Rocket.Chat application in authentik to a policy or group binding so that only the users who should have workspace access can authenticate to it. Without this binding, any authentik user with a valid account may reach the application, even if they were never meant to join your workspace. Test the binding with an account outside the group and confirm it is refused before you open access.
Limiting local password login after SSO is proven
Rocket.Chat keeps its own password login unless you change it, so a local account can remain an alternative path around authentik's controls. Once SSO works for every group that needs access, decide whether to disable or restrict local password sign-in, and keep one documented break-glass administrator account with a strong password and a named owner. Confirm the setting in your Rocket.Chat version, because the exact labels can change between releases.
Multi-factor enforcement at the authentik layer
Enforce MFA in the authentik flow that serves this application, not only in the Rocket.Chat client, so every sign-in path passes through the same second factor. Rocket.Chat's Starter plan includes multi-factor authentication, but authentik remains the point where the policy applies to SSO users. Confirm which authentik stages run for the application, test a login from a new device, and check that enrollment and recovery flows cannot bypass the factor.
Version currency and audit trails
Rocket.Chat states that a version past end of life gets no security or bug fixes, so the platform's security posture depends on staying within a supported line. Its paid plans also list tamper-evident audit trails of messages, files and sessions, which matter if you need to show who accessed what. Confirm your current version's end-of-life date in Rocket.Chat's version durability documentation, and ask your vendor or partner whether your plan includes these audit features.
Common Rocket.Chat and authentik SSO failures and their fixes
This table lists sign-in failures teams often hit when connecting authentik to Rocket.Chat through custom OAuth, with the likely cause, first check, fix and log location for each. The first three failures usually appear during initial setup, and the last three appear after go-live or an upgrade. Make the first check your diagnosis step, and change one setting at a time so you can confirm which change worked.
| Failure | Likely cause and first check | Fix | Where logs live |
|---|---|---|---|
| Redirect URI mismatch | The callback URL configured in authentik differs from the one Rocket.Chat builds from its site URL. First check: compare the scheme, host, port and path of both. | Set the authentik redirect URI to the exact Rocket.Chat callback address, then save and retry a fresh login. | authentik: event log shows the rejected authorization. Rocket.Chat: container output shows the OAuth error. |
| Issuer or discovery URL error | The issuer includes the wrong application slug or a trailing slash, or Rocket.Chat cannot reach the discovery document. First check: open the well-known configuration URL from the Rocket.Chat host or container. | Copy the issuer and discovery URL from the authentik provider page, then fix DNS or certificate trust inside the Rocket.Chat container. | authentik: server container logs. Rocket.Chat: container output for failed discovery requests. |
| Claim names do not match configured fields | The username, email or roles field names in Rocket.Chat differ from the claims authentik sends. First check: inspect the claims returned for the scopes you request. | Align the Rocket.Chat claim fields with the actual claim names, and confirm the requested scopes include email and profile data. | Rocket.Chat: container output shows login errors for missing fields. authentik: token issuance events. |
| Duplicate accounts after login | Rocket.Chat matches existing users by username or email, or the identity field changed after users were created. First check: search Rocket.Chat for a local user with the same email or username. | Clean up or link duplicates before go-live, and choose one stable identifier for matching. Enable account merging only after you confirm matches. | Rocket.Chat: administration user list. authentik: user list showing the sign-in source for each account. |
| Users locked out after disabling local login | Local password login was turned off before the OAuth flow worked for every account, including administrators. First check: confirm at least one administrator can sign in through authentik. | Keep a break-glass administrator account, re-enable local login, test with a standard user, then disable local login again. | Rocket.Chat: container output for failed login attempts. authentik: events for denied or failed flows. |
| Clients fail after an upgrade | Rocket.Chat or authentik moved to a version whose behavior differs from the working setup, or the Rocket.Chat version is past end of life. First check: confirm both versions are supported and read the release notes for each. | Upgrade on a staging copy first, then verify OAuth login and mobile and desktop clients before changing production. | Rocket.Chat: container output at startup. authentik: server container logs after the upgrade. |
Testing the Rocket.Chat SSO path before users depend on it
Test the authentik sign-in path in a staging Rocket.Chat instance, and keep local login working until the pilot passes. The local password path is your rollback, so do not disable it, change the Rocket.Chat custom OAuth provider's login settings in production, or remove existing local accounts until the test results are signed off. Build the staging instance from the same Rocket.Chat version you plan to run in production, and point it at a separate authentik application and provider so that test redirect URIs and client secrets never touch production configuration.
Pick a pilot group that covers the cases the merge and role logic will actually face. Include at least one administrator, one ordinary user, and one user who already has a local Rocket.Chat account with the same email address as their authentik account. The existing-account case is where the username and email claims matter most, because it determines whether authentik logs in to the old account or creates a duplicate. Record for each pilot account the username and email Rocket.Chat shows after login, which group or role the account receives, and whether the account keeps its message history. Confirm the exact claim names and merge behavior against the authentik Rocket.Chat guide and your Rocket.Chat version, since the settings can change between releases.
Repeat the full pilot after every Rocket.Chat upgrade and after every authentik upgrade, not only at first go-live. Rocket.Chat recommends regular upgrades, and the Rocket.Chat version durability page explains that unsupported versions lose security fixes and may stop connecting to official clients, so upgrades will recur on your calendar. A passing test in one version does not prove the OAuth settings still behave the same in the next. Treat a failed repeat test as a release blocker, and keep the local login fallback in place for as long as the SSO path is in use.
Questions teams ask before configuring authentik with Rocket.Chat
How much effort does authentik SSO for Rocket.Chat take?
The effort depends mainly on how many accounts already exist in Rocket.Chat, how many roles you need to map, which Rocket.Chat plan you run, and how many environments (test, staging, production) must be configured. The OAuth provider setup in each system is short. Most of the time goes to agreeing the claims, testing login for existing and new users, and deciding how merged accounts should behave. A small workspace with one role model is a much smaller job than a large workspace with several group-based roles and a staged rollout. Ask for a written scope that lists each environment and each mapping before you compare quotes.
Can our internal team configure authentik with Rocket.Chat without outside help?
Yes, a team that already runs authentik and Rocket.Chat can do this in-house, provided it has the access and time to test. The authentik side needs an OAuth2/OpenID provider and application for Rocket.Chat, following the authentik integrations guide. The Rocket.Chat side needs a custom OAuth configuration under administration. The risk sits in the details: username and email claims, handling of existing local accounts, and role mapping. If no one on the team has done an OAuth login integration before, a fixed-scope engagement can cover the design and the test cases while your team keeps ownership.
What does the integration need from our side?
You need four things. First, administrator access to authentik to create the provider, application, scope mappings and groups. Second, administrator access to Rocket.Chat to configure custom OAuth and role settings. Third, a test window where pilot users sign in without disrupting production messaging. Fourth, a named owner who decides which claims carry usernames, email addresses and roles, and who signs off on how existing accounts are merged. Without that owner, claim decisions tend to stall during testing. Confirm access requirements and test windows with your own change process before work starts.
How long does an authentik and Rocket.Chat SSO integration take?
The duration depends on the same factors as effort: the size of the existing user base, the number of role mappings, the number of environments, and the time your change board needs to approve a production login change. Testing is usually the longest step, because merged accounts and role changes need to be checked with real user populations. The supplied facts do not give a standard duration, so ask any partner or internal lead for a timeline tied to your written scope rather than a generic number.
Which Rocket.Chat plan do we need for SSO and group-based roles?
Rocket.Chat's free Starter plan allows up to 50 users and includes LDAP and Active Directory authentication, single sign-on, and multi-factor authentication, according to the Rocket.Chat plans documentation. Group mapping for LDAP and SAML is listed on the paid plans in the Rocket.Chat pricing page. Confirm with Rocket.Chat which features your chosen plan includes before you design the role model, because a mapping you plan around may depend on a paid tier. Paid plans are priced by quote, so the licensing cost has to come from Rocket.Chat.
How long will our Rocket.Chat version receive security fixes?
Rocket.Chat standard releases are supported for 6 months and LTS releases for 12 months. After end of life, a version receives no security or bug fixes, and cloud services such as the push notification gateway, Marketplace and Omnichannel integrations stop working. Rocket.Chat also says unsupported versions may lose the ability to connect with the official mobile and desktop clients. Check the version durability page before you choose a release line, because the SSO configuration must be retested after each upgrade. Plan that retest as recurring work.
Does a fixed-scope engagement cover upgrades and ongoing support?
A fixed-scope engagement covers what is written in the agreed scope, deliverables and timeline, and nothing beyond that. For this integration, that usually means the authentik provider and application, the Rocket.Chat custom OAuth configuration, the claim and role design, the merge approach for existing accounts, test cases and a handover. Upgrades of Rocket.Chat or authentik, and continuing support, are separate. DeployOpen offers ongoing support and upgrades as retainers. Ask for the list of included items and exclusions in the written scope.
How DeployOpen scopes and delivers this integration
DeployOpen plans and builds the authentik and Rocket.Chat SSO integration inside your own infrastructure, from the authentik OAuth2/OIDC provider to the Rocket.Chat custom OAuth login. Each step is agreed in writing, tested against your identity and claim requirements, and documented so your team can run it afterward.
How we scope
- Engagements are fixed-scope, with the authentik and Rocket.Chat versions, hosting model and login requirements agreed in writing first.
- The written scope names the claims to be mapped, how existing Rocket.Chat accounts will be matched, and which role mappings are included.
- Ongoing support, upgrades and continuous testing can be added later as a retainer, priced separately from the fixed-scope build.
How we build
- We configure the authentik provider and Rocket.Chat custom OAuth settings together, checking redirect URIs and scopes against your environment.
- Username and email claims are mapped and tested with real sign-in attempts before any user is moved onto the new login path.
- Existing user merging and role mapping are rehearsed on a non-production copy so account behavior is verified before cutover.
How we hand over
- You receive configuration records, claim and role mapping tables, and the test cases used to verify each login path.
- A runbook covers rotating client secrets, adding roles, and handling accounts that fail to match during sign-in.
- Your team walks through the handover session, so administrators can make routine changes without outside help.
How we support
- Support can cover Rocket.Chat version upgrades, since unsupported versions stop receiving security fixes and can lose client compatibility.
- Changes to authentik releases are reviewed against the integration before you upgrade either side of the connection.
- Confirm with your team which Rocket.Chat plan supports the group mapping and SSO features you need before the scope is signed.
