🔓 OmniAuth Rocket Chat

This unofficial OmniAuth strategy allows your application's users to authenticate with Rocket Chat as the identity provider (aka social login).

• Ruby >= 3.2.0.
• A Rocket Chat release that isn't EOL. See Compatibility below.

Rocket Chat doesn't store the PKCE code challenge, so the token exchange fails with Invalid grant: code verifier is invalid. Until this is resolved, set pkce: false in the configurations below.

Tested with omniauth-rocketchat v0.2.0 against the first and the latest patch release of every Rocket Chat minor version that isn't EOL. Minor versions show the result of their latest patch release. The first patch release is listed separately when it differs.

A scheduled workflow keeps this matrix up to date. EOL versions are not supported. Use bin/compat to check a specific version.

Add this line to your application's Gemfile:

gem 'omniauth-rocketchat'

Then execute bundle install.

To enable third-party login, register your application in Rocket Chat to obtain the Client ID and Client Secret. Add your application's host(s) to whitelist callback redirects by following these steps:

1. Log in to your Rocket Chat instance as an administrator.
2. Navigate to Administration > Third-party login (e.g., https://example.com/admin/third-party-login).
3. Click New Application:
   • Enable the Active checkbox.
   • Enter an Application Name and Redirect URL (e.g., https://example.com/users/auth/rocketchat/callback for Devise).
   • Click Save.
4. Select your new application and copy the Client ID and Client Secret.

Choose one of the following methods to integrate the strategy with your Ruby application.

use OmniAuth::Builder do
  provider(
    :rocketchat, 
    ENV["CLIENT_ID"],
    ENV["CLIENT_SECRET"], 
    pkce: false,
    client_options: {
      site: "https://example.com"
    }
  )
end

If you modified the endpoint URL's in Rocket Chat, set authorize_url and token_url.

use OmniAuth::Builder do
  provider(
    :rocketchat,
    ENV["CLIENT_ID"],
    ENV["CLIENT_SECRET"],
    pkce: false,
    client_options: {
      site: "https://example.com",
      authorize_url: "/custom/oauth/authorize",
      token_url: "/custom/oauth/token"
    }
  )
end

Set the name option to distinguish between multiple Rocket Chat instances. It appears in the OmniAuth auth hash request.env["omniauth.auth"] under the provider key.

use OmniAuth::Build do
  provider(
    :rocketchat,
    ENV["CLIENT_ID"],
    ENV["CLIENT_SECRET"],
    name: :some_other_name,
    pkce: false,           
    client_options: {
      site: "https://example.com"
    }
  )
end

Choose one of the following methods to integrate the strategy with your Ruby on Rails application. The Custom Endpoints and Identifier options apply here as well.

# config/initializers/rocketchat.rb
Rails.application.config.middleware.use OmniAuth::Builder do
  provider(
    :rocketchat,
    ENV["CLIENT_ID"],
    ENV["CLIENT_SECRET"],
    pkce: false,           
    client_options: {
      site: "https://example.com"
    }
  )
end

Use this integration if you use Devise with the :omniauthable module.

# config/initializers/rocketchat.rb
Devise.setup do |config|
  config.omniauth(
    :rocketchat,
    ENV["CLIENT_ID"],
    ENV["CLIENT_SECRET"],
    pkce: false,
    client_options: {
      site: "https://example.com"
    }
  )
end

This strategy returns information about the authenticated user in the Auth Hash Schema 1.0+. The following information is available in the info hash:

• name: The user's full name.
• nickname: The user's Rocket Chat username.
• email: The user's email address. The strategy prioritizes verified email addresses but will fall back to the first available one if no verified address is found.
• email_verified: A boolean indicating whether the email address has been verified on the Rocket Chat instance.
• image: The URL to the user's avatar.

You can find the complete profile information returned by Rocket Chat in extra.raw_info.

Rocket Chat also returns access and refresh tokens along with other information in the credentials hash.

After checking out the repo, run bin/setup to install dependencies. Then run bundle exec rake to run the specs and the linter.

bin/compat runs the full OAuth flow against real Rocket Chat instances: request phase, user consent, token exchange, and profile fetch. It tests both pkce: true and pkce: false, and prints the result of each flow, a compatibility matrix and a plain-language summary. It exits non-zero if any flow fails.

By default, it starts throwaway Docker containers (MongoDB and Rocket Chat) for each version you pass. It removes them afterwards. Versions are rocketchat/rocket.chat image tags. Docker is required.

bin/compat 8.9.0              # a single version
bin/compat 8.2.0 8.9.0        # several versions, one matrix
bin/compat --keep 8.9.0       # keep the containers running for debugging
bin/compat --mongo mongo:7.0 8.2.0  # use another MongoDB image (default: mongo:8.2)

You can also test unreleased code, e.g. to check whether an upstream fix works. The script uses the images Rocket Chat's CI publishes to ghcr.io/rocketchat/rocket.chat. These exist for the develop branch and for pull requests from branches of the Rocket.Chat repository, not for pull requests from forks. The matrix shows the commit each image was built from.

bin/compat --pr 42686                  # a pull request
bin/compat --ref develop               # a branch
bin/compat 8.9.0 --ref develop         # mix with released versions in one matrix

Set GITHUB_TOKEN (or GH_TOKEN) if you hit GitHub's API rate limit.

You can also test against an existing instance. The user needs permission to manage OAuth apps:

ROCKETCHAT_PASSWORD=secret bin/compat --site https://chat.example.com --user admin

The script registers a temporary OAuth app with the redirect URL http://localhost:4567/auth/rocketchat/callback and deletes it afterwards. Run bin/compat --help for all options.

Pass --json FILE to also write the results as JSON. Once a day, the compatibility workflow uses it to test the latest release of this gem against the first and the latest patch release of every Rocket Chat minor version that isn't EOL. bin/compat-matrix caches the results per gem release and Rocket Chat version in .github/compat.json, so each combination is tested only once. It then updates the Compatibility Matrix and opens a pull request. To retest a combination, delete its entry from the cache.

This library aims to adhere to Semantic Versioning 2.0.0. Violations of this scheme should be reported as bugs.

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Bug reports and pull requests are welcome on the GitHub project page.

Copyright © 2024-2026 David Uhlig. See LICENSE for details.