--- title: "Rocket Chat Iframe Authentication Setup" slug: "configuring-iframe-auth" description: "Configure Iframe authentication in Rocket Chat. Securely embed chat and enable trusted collaboration workflows." updated: 2026-11-02T10:34:39Z published: 2026-11-02T10:34:39Z canonical: "developer.rocket.chat/configuring-iframe-auth" --- > ## Documentation Index > Fetch the complete documentation index at: https://developer.rocket.chat/llms.txt > Use this file to discover all available pages before exploring further. # Configuring Iframe Authentication Iframe authentication in Rocket.Chat enables user authentication via your custom login page in your web application, rather than the Rocket.Chat login page. This can be useful if you want to have a single sign-on system for your website and Rocket.Chat. This guide will walk you through setting up iframe authentication in Rocket.Chat. To enable iframe integration in your workspace, navigate to **Manage → Workspace → Settings → Accounts → Iframe** and toggle on **Enabled**. You will also find the following settings in the Iframe section: - **Iframe URL** - **API URL** - **API Method** When iframe is enabled, Rocket.Chat communicates with a third-party application to verify if a user is logged in. If the user isn't authenticated, Rocket.Chat displays the iframe URL within an iframe, enabling them to log in on the third-party website. This process ensures the user's authentication not just on the third-party site but also within Rocket.Chat. > For more information on the iframe authentication flow, see this [NodeJs example app](https://github.com/RocketChat/iframe-auth-example). ## Configuring API URL and API Method Rocket.Chat utilizes an API URL and API method to facilitate user login and authentication verification within your third-party application. - The **API URL** is an endpoint in your third-party application that is responsible for confirming the user's login status. - The **API Method** is used to select the submission method Rocket.Chat will use to submit information to the **API URL**, e.g., `POST`. When a user is logged into the third-party application, the API URL connects with Rocket.Chat and sends back a JSON object containing a token or loginToken property. If the user is not logged in, the **API URL** responds with an empty body and a 401 status code. The property returned by the API URL varies based on how the third-party application interacts with Rocket.Chat. Enabling iframe integration changes the login flow for Rocket.Chat mobile applications (Android & iOS). When this setting is enabled, the mobile app bypasses the default login interface and attempts to load the authentication page within a WebView. For this process to work correctly, you must ensure that: - The Iframe setting is set to **Enabled**. - The **Iframe URL** is defined. - The **API URL** is defined. Note that enabling iframe without defining the valid URLs may cause the mobile application to close unexpectedly or fail to load the login screen, as the WebView will not have a valid target to render. ## Interacting with Rocket.Chat iframe Interaction with Rocket.Chat iframe can be through the Rocket.Chat API or by managing MongoDB directly. - **Using Rocket.Chat API**: You can use [Rocket.Chat's REST APIs](/v1-api/docs/login-with-username-and-password) to authenticate the user if you have the user's password stored, or if it is the same between your third-party system and Rocket.Chat. This way, you receive an `authToken` back from Rocket.Chat that should be returned as `loginToken` by your endpoint. If the user does not have a Rocket.Chat account, you can either [create a user](/v1-api/apidocs/create-user) as an admin or [register them](/v1-api/apidocs/register-user) using the Rocket.Chat REST API. ```json {  "loginToken": "already-saved-or-returned-login-token" } ``` - **Managing MongoDB directly**: Here, you have access to Rocket.Chat's database, you can connect there directly and manage the user records yourself. It is useful if you already have MongoDB on your stack and don't want to learn Rocket.Chat's API. The endpoint should connect to Rocket.Chat's MongoDB database and ensure the `generated-token` is saved on `users` collection on the corresponding user record. The `generated-token` should be saved on the field path `services.iframe.token`. Here is a snippet of the user record: ```json {  "_id": "MZiFvWAf96876875u",  "createdAt": new Date(1432252673528),  "services": {    "iframe": {      "token": "generated-token"    }  },  "emails": [    {      "address": "useremail@gmail.com",      "verified": true    }  ],  "name": "John Doe",  "username": "john.doe",  "active": true,  "statusDefault": "online",  "roles": [    "user"  ],  "type": "user" } ``` Here is a snippet of the response: ```json {  "token": "generated-token" } ``` ## Configuring iframe URL **Iframe URL** is the URL of the webpage you want to embed as the login page of your Rocket.Chat instance. It can be developed using any programming language/framework of your choice. This login page communicates back to Rocket.Chat using `postMessage` API. When a user logs in to your website or application, you need to authenticate them with Rocket.Chat so that they can access the chat functionality. This authentication process involves sending a request to Rocket.Chat's API URL endpoint with the user's login credentials. Once the user is authenticated, render the chat interface within an iframe on your application. To do this, return a JavaScript code to execute within the iframe and handle the authentication on the Rocket.Chat side. This JavaScript code varies depending on how you logged in the user. - If you have used Rocket.Chat's APIs to log in the user or already have the user's token saved on your end, return: ```javascript ``` - If you have saved a user's token connecting directly to Rocket.Chat's database on the user's field `services.iframe.token`: ```javascript ``` If the login fails, Rocket.Chat replies to your page with a `login-error` event. ## Using OAuth configured on Rocket.Chat's auth Your login page can also start a login through an OAuth service configured in your workspace. Send the `call-custom-oauth-login` command with the name of the service: ```javascript window.parent.postMessage({  event: 'call-custom-oauth-login',  service: 'your-oauth-service-name' }, 'http://your.rocket.chat.url'); ``` Rocket.Chat replies with a `custom-oauth-callback` event. This command is one of the iframe integration commands, so it works only if **Enable receive** is turned on in **Manage → Workspace → Settings → General → Iframe integration** and **Receive origins** allows your login page's origin. For details, see [Iframe Integration: Sending Commands](/v1/docs/iframe-integration-sending-commands). **Log in to Rocket.Chat with the default account system while in development** > [!CAUTION] > When iframe authentication is enabled, the default Rocket.Chat login page isn't available on your workspace. To log in with your Rocket.Chat credentials, for example while you develop your login page, turn off iframe authentication temporarily. 1. Add the following environment variable to your Rocket.Chat deployment and restart the server: ```bash OVERWRITE_SETTING_Accounts_iframe_enabled=false ``` 2. Log in with your Rocket.Chat username or email and password. 3. When you're done, remove the variable and restart the server. The variable saves the setting as turned off, so turn **Enabled** back on in **Manage → Workspace → Settings → Accounts → Iframe**. For details, see [Manage Settings Using Environmental Variables](https://docs.rocket.chat/docs/manage-settings-using-environmental-variables). With the iframe authentication properly set up, test it as described in [Testing Iframe Authentication](/v1/docs/testing-the-iframe-authentication).