---
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-02-09T06:28:32Z
published: 2026-02-09T06:28:37Z
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 [**using Rocket.Chat API**](/v1/docs/configuring-iframe-auth) or [**managing MongoDB directly**](/v1/docs/configuring-iframe-auth).
- **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
```
## Using OAuth configured on Rocket.Chat's auth
Suppose you have OAuth services configured on Rocket.Chat, you can trigger them from within your login page as well. To implement this authentication, you will receive a `postMessage` back from Rocket.Chat after triggering the OAuth authentication with the user's credentials response from the OAuth service. You need to manage the user creation/authentication on Rocket.Chat's database by yourself, as described earlier.
### Facebook
```javascript
window.parent.postMessage({
event: 'call-facebook-login',
permissions: ['email']
}, 'http://your.rocket.chat.url');
```
The reply will be either a postMessage or an error back to your page.
**PostMessage**
```node-repl
{
event: 'facebook-login-success',
response: {
// authResponse: Object
// accessToken: "a7s6d8a76s8d7..."
// expiresIn: "5172793"
// secret: "..."
// session_key: true
// sig: "..."
// userID: "675676576"
// status: "connected"
}
}
```
**Error**
```node-repl
{
event: 'facebook-login-error',
error: error,
response: response
}
```
### Google
```javascript
window.parent.postMessage({
event: 'call-google-login',
// scopes:
// webClientId:
}, 'http://your.rocket.chat.url');
```
The reply will be either a postMessage or an error back to your page.
**PostMessage**
```node-repl
{
event: 'google-login-success',
response: {
// "email": "rodrigoknascimento@gmail.com",
// "userId": "1082039180239",
// "displayName": "Rodrigo Nascimento",
// "gender": "male",
// "imageUrl": "https://lh5.googleusercontent.com/-shUpniJA480/AAAAAAAAAAI/AAAAAAAAAqY/_B8oyS8yBw0/photo.jpg?sz=50",
// "givenName": "Rodrigo",
// "familyName": "Nascimento",
// "ageRangeMin": 21,
// "oauthToken": "123198273kajhsdh1892h"
}
}
```
**Error**
```node-repl
{
event: 'google-login-error',
error: error
}
```
### Twitter
```javascript
window.parent.postMessage({
event: 'call-twitter-login'
}, 'http://your.rocket.chat.url');
```
The reply will be either a postMessage or an error back to your page.
**PostMessage**
```node-repl
{
event: 'twitter-login-success',
response: {
// "userName": "orodrigok",
// "userId": 293123,
// "secret": "asdua09sud",
// "token": "2jh3k1j2h3"
}
}
```
**Error**
```node-repl
{
event: 'twitter-login-error',
error: error
}
```
**Login to Rocket.Chat with the default account system while in development**
> [!CAUTION]
> When you activate the iframe auth, you cannot access Rocket.Chat's default login page on your workspace. However, if you still want to use your Rocket.Chat's credentials to log in on your workspace, you can do that by opening the browser's developer console and executing the following code:
```javascript
Meteor.loginWithPassword('username-or-email', 'your-password');
```
With the iframe authentication properly set up, let's now move forward to [testing the iFrame authentication](/v1/docs/testing-the-iframe-authentication).