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. Realm:

  • Uses role-based data access rules to determine read & write permissions.
  • Associates every request with an authenticated user
  • Evaluates permissions for every object included the request.

Through user accounts, you can store and access metadata and custom data for each user.

Users log in through authentication providers. Each provider represents a specific method of authentication.

Realm includes built-in providers for common use cases, such as Facebook and Google. Custom providers allow you to integrate any external authentication system.

In MongoDB Realm, an authentication provider is a modular service. These services provide identity verification, and maintain information about app users.

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

Realm includes built-in authentication providers for common use cases. This includes:

You can configure custom providers to integrate external authentication systems.

  • Custom JWT: provider accepts JSON web tokens signed by the external system.
  • Custom Function: provider allows you to define custom login logic in a Realm Function.
Realm Applications Require User Authentication

Every application must have at least one authentication provider configured and enabled. Without at least one provider, no client application can connect. To learn how to configure and enable authentication providers, see: Authentication Providers.

A user account represents a single, distinct user of your application. Realm creates the user when an authentication provider validates a unique identity. You can source user metadata, such as email or birthday, from authentication providers. You can associate each user with custom data.

MongoDB Realm stores login metadata for a user in an authentication provider identity. Realm uses this metadata to authenticate the user.

Upon first login with an authentication provider, Realm creates an identity object. Each object contains a unique ID, and provider-specific metadata about the user. On later logins, MongoDB Realm refreshes the existing identity data.

A single user account can have more than one identity. Realm client SDKs enable you to link identities to existing user accounts. This allows users to log in to a single account with more than one provider. For more information, see the documentation on linking identities for your client SDK.

In the Realm SDKs, you can log in more than one user, but only one account can be active at any given time. The active user is a user account associated with an application request.

MongoDB Realm executes requests from client applications as the active user. Realm replaces dynamic references to the user - e.g. %%user in a JSON expression - with the active user.

You can use a specific active user, or the system user, to execute Functions.

The system user is an internal user that has advanced privileges. The system user bypasses all rules. You can execute functions as a system user instead of the user making a request. Triggers run in the context of the system user.

The system user is useful for administrative tasks. This includes:

  • Tasks that need to circumvent rules and queries
  • Tasks that need unrestricted access to MongoDB CRUD and aggregation operations
Security Warning

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

For example, use function context to check if the active user can call the system function. Define a condition to determine whether the user has the appropriate permissions, 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")

User session describes the period when an authenticated user can access data in your app. Authenticated users can use app data without re-entering a password or re-authenticating.

MongoDB Realm manages sessions with access tokens and refresh tokens. Client SDKs supply the logic to manage tokens, and provide them with requests.

The access token for a session expires after thirty minutes. Clients can use the refresh token to retrieve a new access token and start a new session. Refresh tokens expire after thirty days.

Realm SDKs manage refresh access tokens for you. You don't need to manage this process yourself when implementing client applications.

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

  • Deletes the local session information by deleting both the access and refresh tokens.
  • 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. If a malicious user gets the access token, he or she could use the token to continue making requests. These requests would appear to come from the user who "logged out." This window would last for up to thirty minutes (that is, until that access token expires).

You can use revoke all sessions for a specific user. This invalidates all access tokens and refresh tokens for that user. See the Revoking User Sessions page for the specific steps.

  • Realm supports authentication and user accounts through a variety of authentication providers. You can associate users with more than one authentication provider.
  • MongoDB Realm supports having more than one user 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.
  • Realm SDKs manage the access and refresh tokens that comprise a user session.
←  Sync Production Load TestingUser Objects →
Give Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.