Prepare for Authentication Changes in 9.0.0

In Rocket.Chat 9.0.0 and later, LDAP, SAML, and Custom OAuth require a premium plan, and Drupal, Facebook, LinkedIn, Meteor, X (formerly Twitter), WordPress, and Dolphin logins are removed. Community workspaces must upgrade their plan or migrate users to an authentication method available in Community before updating to 9.0.0 or later; otherwise, users who sign in with these methods are unable to log in.

In this guide, workspace administrators will learn how to:

• Prepare your Community workspace before updating to 9.0.0

• Recover access after updating to 9.0.0

• Troubleshoot common login issues

Authentication methods in Rocket.Chat 9.0.0

The following table shows which authentication methods are available on each plan from Rocket.Chat 9.0.0:

Depending on whether you want to keep your current authentication provider, choose one of the following:

1. Keep LDAP, SAML, or Custom OAuth: Before you update to 9.0.0, upgrade from Community to Starter or contact Sales to purchase a premium plan.

   Starter is available free of charge for eligible organizations with up to 50 users and one workspace per organization.

2. Stay on the Community plan: Prepare your Community workspace so that administrators and users can log in with a supported method after the update.

Prepare your Community workspace before updating to 9.0.0

If you plan to remain on the Community plan, complete the following steps before you update to 9.0.0.

Before upgrading, make sure at least one workspace administrator can log in with a local Rocket.Chat username and password.

Step 1: Show the default login form

Workspaces that use an external authentication provider sometimes hide the default username and password fields. To show them on the login page:

1. Go to Manage > Workspace > Settings > Layout > Login.

2. Enable Show Default Login Form.

3. Click Save Changes.

The login page now displays the username or email and password fields. For more details, see Customize Workspace Layout.

Step 2: Set a local password for an administrator

Give at least one administrator a local Rocket.Chat password that doesn't depend on an external identity provider.

If the administrator currently signs in with LDAP, SAML, or OAuth, set the local password on their existing account. You don't need to create a new account.

1. Go to Manage > Workspace > Users.

2. Select a user with the admin role and click Edit.

3. Under Password, select Set manually.

4. Enter and confirm a secure password.

5. Click Save user.

If your workspace email is configured, you can select Set randomly and send by email instead. For additional protection, create a dedicated emergency administrator account that uses local authentication.

Step 3: Review account and email settings

1. Go to Manage > Workspace > Settings > Accounts and review the following settings:

2. Go to Manage > Workspace > Settings > Email > SMTP. Click Send a test mail to my user to confirm that emails work if users attempt to reset their passwords by email. A test email arrives in your inbox if SMTP is configured correctly.

For more details, see Accounts Settings and Configure Email.

Step 4: Test local login

1. Open your workspace in a private or incognito browser window.

2. In the username or email and password fields, enter the administrator credentials you set in Step 2.

3. Log in and confirm that you can access Manage > Workspace.

If you can't log in, resolve the issue before you update your workspace.

Step 5: Move other users to a supported login method

Users who currently sign in with LDAP, SAML, or Custom OAuth need a login method available on Community. You can do any of the following:

• Set local passwords for existing users in Manage > Workspace > Users.

• Ask users to set their own passwords if the Allow Password Change setting is enabled.

• Migrate users to a supported OAuth provider, verifying that they retain access to their existing accounts.

Test the new authentication method before disabling the previous one.

After you complete these steps, review the Guidelines for Updating Rocket.Chat and update your workspace to 9.0.0.

Recover access after updating to 9.0.0

If you have already updated your workspace to 9.0.0 and can't log in, use any of the following recovery options:

Option 1: Log in with local credentials

If you already have a local password:

1. Go to your Rocket.Chat workspace.

2. Login with your local username/email and password.

If you don't have a local password, you can:

• Click Forgot password on the login page. This works only if password reset is enabled and workspace email delivery works.

• Ask another administrator who can still log in to set a password for your existing account in Manage  > Workspace > Users.

Option 2: Restore the default login form

If the login page shows only external login options, enable the default login form with an environment variable or by updating MongoDB.

These methods only restore the login form. You still need an account with a valid local password to log in.

Method A: Use an environment variable

1. Add the following environment variable to your Rocket.Chat deployment configuration:

   OVERWRITE_SETTING_Accounts_ShowFormLogin=true

2. Apply the configuration and restart your Rocket.Chat server.

For deployment-specific instructions, see Manage Settings Using Environmental Variables.

Method B: Update the setting in MongoDB

1. Connect to your MongoDB instance. For Docker deployments, open the MongoDB shell with:

   docker exec -it <mongodb-container-name> mongosh

2. Select your Rocket.Chat database. This example uses rocketchat:

   use rocketchat

3. Enable the default login form:

   db.rocketchat_settings.updateOne({ _id: "Accounts_ShowFormLogin" }, { $set: { value: true } })

4. Refresh the workspace login page.

The username or email and password fields appear on the login page. Log in with your local username or email and password.

Option 3: Reset an administrator password in MongoDB

If no administrator can log in and none has a local password, set a new password on an existing administrator account directly in MongoDB. You need access to the workspace database.

Only authorized administrators should modify the database directly. Back up the database before you start, and never store plain-text passwords in MongoDB.

1. Open the MongoDB shell and select your Rocket.Chat database:

   use rocketchat

2. Generate and copy a bcrypt hash of a temporary password. This example uses Python with the bcrypt package installed:

   import bcrypt
   
   password = b"YourSecureTemporaryPassword"
   print(bcrypt.hashpw(password, bcrypt.gensalt(rounds=10)).decode())

3. Update the administrator's password. Replace <admin-username> with the existing administrator username and <bcrypt-hash> with the hash from the previous step:

   db.users.updateOne(
     { username: "<admin-username>" },
     {
       $set: {
         "services.password.bcrypt": "<bcrypt-hash>"
       }
     }
   )

   The command result shows one matched and one modified document.

4. Open your workspace and log in with the administrator username and the temporary password.

5. Change the temporary password to a new secure password.

6. Confirm that you can access workspace administration.

For more details, see Restoring an Admin User.

Option 4: Change your workspace plan

If you want to continue using LDAP, SAML, or Custom OAuth, contact the Rocket.Chat Sales team to upgrade to a premium plan that supports these authentication methods. Eligible Community workspaces can upgrade to the free Starter plan through the Rocket.Chat Cloud Portal. See Change Your Workspace Plan for more details.

After the license for the new plan has been synchronized with your workspace, try logging in with your previous authentication method. If the license does not synchronize automatically and you cannot access the workspace administration interface, contact your deployment administrator or Rocket.Chat Support for assistance.

Troubleshooting

Next steps

After you restore access, confirm that all administrators and users can log in with a method available on your current plan. Refer to Deprecated and Phasing Out Features for changes that affect your workspace.

Related topics

• Authentication & SSO

• Accounts Settings

• Manage Workspace Users

• Customize Workspace Layout

• Restoring an Admin User

• Change Your Workspace Plan