Docs Menu

Users & Authentication

On this page

  • Introduction
  • Concepts
  • Authentication Providers
  • User Accounts
  • Authentication Provider Identities
  • Active User
  • System User
  • User Sessions
  • Summary

MongoDB Realm manages authentication for your application's end users and allows you to store and access metadata for each user. Every request in MongoDB Realm is associated with an authenticated user, which enables MongoDB Realm's role-based data access rules to dynamically determine read & write permissions for every object included in their request.

Users log in through modular authentication providers that each represent a specific method of authentication. MongoDB Realm includes several built-in providers for common use cases as well as custom providers that allow you to integrate any external authentication system.

An authentication provider is a modular service that maintains information about your application's users and allows them to verify their identity.

Users authenticate themselves by providing a set of credentials to an authentication provider. If the credentials are valid, the provider returns a unique identity associated with the user and MongoDB Realm logs them in as the active user.

MongoDB Realm includes built-in authentication providers for common use cases, including anonymous users, email/password combinations, API keys, and OAuth 2.0 through Facebook, Google, and Apple ID.

You can also configure your own custom authentication providers to integrate external authentication systems. The Custom JWT provider accepts JSON web tokens signed by the external system and the Custom Function provider allows you to define custom logic in a Realm Function.

User Authentication is Required

Every application must have at least one authentication provider configured and enabled before any client application can successfully connect. For more information on how to configure and enable authentication providers, see Authentication Providers.

A user account represents a single, distinct user of your application. Every user account has a unique ID and is associated with at least one authentication provider identity. MongoDB Realm automatically sources user metadata, such as their email address or birthday, from authentication providers and allows you to associate each user with custom data stored in a collection of your linked MongoDB Atlas data source.

Link Multiple Identities to One User Account

When a user authenticates with a provider for the first time, MongoDB Realm creates a new account and associates the authenticated identity with that account. Some providers allow you to associate the identity with an existing user account instead of creating a new one. This allows users to log in to the same account with multiple authentication providers. For more information, see the documentation on linking identities for your client SDK.

An authentication provider identity is a set of metadata about a user that MongoDB Realm obtains from each authentication provider used to authenticate that user. A single user account can have multiple identities if the user associates their account with multiple authentication providers.

When a user first logs in with an authentication provider, MongoDB Realm associates the user with an identity object that contains a unique identifier and additional, provider-specific metadata about the user. On subsequent logins, MongoDB Realm refreshes the existing identity data but does not create a new identity.

In the Realm SDKs, multiple users can log in simultaneously, but only one account can be active at any given time. The active user is a user account associated with an application request. When MongoDB Realm receives a request from a client application, it executes the request in the context of the active user, replacing any dynamic references to the user (e.g. %%user in a JSON expression) with the active user's information.

In most circumstances, the active user is the authenticated user that issued a request. You can also configure a specific active user for Functions, Triggers, and webhooks or choose to use the system user instead.

The system user is an internal user that has advanced privileges and automatically bypasses all rules. You can configure Functions and incoming webhooks to run in the context of the system user instead of the user account that issued a request. Triggers always run in the context of the system user.

The system user is useful for administrative tasks that need to circumvent rules and queries that need unrestricted access to MongoDB CRUD and aggregation operations.

Security Warning

Rules do not apply to the system user, which means that Functions and webhooks that run as the system user can become a security liability. Ensure that you do not expose these functions to unauthorized users.

For example, you can use function context to check if the active user is allowed to call the system function based on a condition that you define, e.g.:

exports = function() {
const activeUser = context.user
const adminUserId = context.values.get("adminUserId");
if( == adminUserId) {
// The user can only execute code here if they're an admin.
} else {
throw Error("This user is not allowed to execute the system function")

A user session is a user's state of being authenticated with your app for a certain period of time. While a user is authenticated, they can interact with app data without needing to enter their password or otherwise re-authenticate.

Sessions are managed with access tokens and a refresh token provided by MongoDB Realm. The client SDKs implement the logic of managing these tokens and providing them to MongoDB Realm when making requests.

For web browsers, the JavaScript SDK stores these tokens in HTML5 local storage. In the Android SDK, they are stored in Shared Preferences. In the iOS SDK, they are stored in the Keychain.

The access token for a session expires after thirty minutes. However, a new session can be started by retrieving a new access token from MongoDB Realm using the refresh token. The SDKs automatically take care of refreshing access tokens, so you do not need to worry about this when implementing client applications.

You can invalidate a refresh token by calling the logout() method on the client, which does two things:

  • It deletes the local session information by deleting both the access and refresh tokens.
  • It invalidates the refresh token in the MongoDB Realm backend.

The logout() method provided by the SDKs does NOT invalidate any active sessions on the server. This means that if you somehow expose the access token to a malicious user before logout() is called, the malicious user could theoretically use the token to continue making requests on behalf of the user who "logged out" for up to thirty minutes (that is, until that access token expires).

The user list under the Users tab, on the App Users page of the Realm admin console, provides a way to revoke all sessions for a specific user. This will invalidate all access tokens and refresh tokens for that user. See the Revoking User Sessions page for the specific steps.

  • MongoDB Realm supports authentication and user accounts through a variety of authentication providers. Users can associate themselves with multiple authentication providers and have identity information from multiple providers.
  • MongoDB Realm supports having multiple users logged in at the same time. There is only one active user at a time.
  • The system user is a special user in MongoDB Realm that bypasses all rules.
  • MongoDB Realm handles the access tokens and refresh tokens that comprise a user session automatically.
Give Feedback
© 2021 MongoDB, Inc.


  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.