• Realm >
• Users & Authentication >
• User Management

Enable Custom User Data

Overview

You can store arbitrary data about your application users in a MongoDB collection and configure MongoDB Realm to automatically expose each user’s data in a field of their user object. For example, you might store a user’s preferred language, date of birth, or their local timezone.

MongoDB Realm automatically finds a user’s custom data document and includes it in their access token when they log in. You can access the data in the custom_data field of the user’s object in function context, the %%user expansion, and their client application access token.

MongoDB Realm does not manage custom user documents so you are responsible for creating and deleting them. The underlying data is a regular MongoDB document, so you can use standard CRUD operations through the MongoDB Atlas service to define and modify a user’s custom data. You can also use authentication triggers to dynamically update user documents, such as storing the time of their most recent login in the lastLogin field.

Example

You can access custom user data in the client SDKs as well as functions and rule expressions.

• Functions
• JSON Expressions

copy

const user = context.user;
const speaksEnglish = user.custom_data.primaryLanguage === "English";

copy

{
  "%%user.custom_data.primaryLanguage": "English"
}

Store One Document Per User

Documents that contain user data must include the user’s ID in a specific field. If multiple documents specify the same user’s ID, MongoDB Realm only exposes the data from the document that was inserted first.

Custom Data May Be Stale

MongoDB Realm does not dynamically update a user’s custom data if the underlying document changes. Instead, MongoDB Realm fetches a new copy of the data whenever a user refreshes their access token, such as when they log in. This may mean that the custom data won’t immediately reflect changes, e.g. updates from an authentication Trigger. The client SDKs automatically refresh a logged-in user’s access token periodically, so the user’s custom data should never remain stale for more than 30 minutes.

Configuration

MongoDB Realm stores MongoDB documents that correspond to custom user data in a linked MongoDB Atlas cluster. When you configure custom user data for your application, you specify:

• the custom user data cluster
• the custom user data database
• the custom user data collection in which custom user data documents are stored
• the user ID field used to map custom user data documents to users (via user ID)

Configure Permissions for Custom User Data

Because custom user data belongs to a specific user, it could contain personal or private information depending on the needs of your application. If your application stores such information in custom user data, you should restrict access to custom user data appropriately. While the permissioning model of your custom user data depends on the needs of your application, consider using one of the following permission models to restrict read and write access to privileged users only:

• Make your custom user data readable and writable by only the user whose ID matches the user ID field of each custom user data document. In this permissioning model, the user writes custom user data using MongoDB Data Access or Sync.
• Make your custom user data readable and writable by only a system user in a system function. Create a system function that handles edits to custom user data for a user using the user.id value provided by the function context. In this permissioning model, the user writes custom user data using the Functions API.

Procedure

• Realm UI
• Realm CLI

1

Navigate to the Custom User Data Configuration Screen

You can configure and enable customer user data in the Realm UI. To get to the configuration page, click Users in the left-hand navigation and then select the Custom User Data tab.

2

Enable Custom User Data

To configure MongoDB Realm to associate data in a collection with your application’s users, set the Enable Custom User Data toggle to On.

3

Specify the Custom User Data Collection

You must store the custom data for your application’s users in a single collection of a linked MongoDB Atlas cluster. To configure your application to read user data from this collection, you need to specify the following values:

• Cluster Name: The name of a linked MongoDB cluster that contains the custom user data collection.
• Database Name: The name of the MongoDB database that contains the custom user data collection.
• Collection Name: The name of the MongoDB collection that contains custom user data.

4

Specify the User ID Field

Every document in the custom user data collection should have a field that contains the user ID of the Realm user that it describes. Specify the name of the field that contains each user’s ID in the User ID Field input.

5

Deploy the Updated Application

Once you have configured the customer user data collection, you can make custom user data available to client applications by deploying your application. To deploy a draft application from the Realm UI:

1. Click Deploy in the left-hand navigation
2. Find the draft in the deployment history table and then click Review & Deploy Changes.
3. Review the diff of changes and then click Deploy.

Once the application successfully deploys, Realm begins to associate custom data with users. When a user logs in, Realm automatically queries the custom user data collection for a document where the specified User ID Field contains the user’s ID. If a document matches, Realm exposes the data in the document in the custom_data field of that user’s user object.

1

Export Your Realm Application

You can set up and enable custom user data through realm-cli or automatic GitHub deployment. To configure custom user data, you need the latest version of the application directory for your application.

You can export your application from the Export tab of the Settings page in the Realm UI, or by running the following command from an authenticated instance of realm-cli:

copy

realm-cli export --app-id=<App ID>

2

Configure Custom User Data

You must store the custom data for your application’s users in a single collection of a linked MongoDB Atlas cluster. Every document in the collection should have a field that contains the user ID of the Realm user that it describes.

To configure your application to read user data from this collection, specify a configuration document in the custom_user_data_config field of config.json:

copy

config.json

{
  ...,
  "custom_user_data_config": {
    "enabled": <boolean>,
    "mongo_service_id": "<Linked MongoDB Cluster Service ID>",
    "database_name": "<Database Name>",
    "collection_name": "<Collection Name>",
    "user_id_field": "<User ID Field Name>"
  }
}

Field	Description
enabled	A boolean that, if true, indicates that Realm should associate data in the specified collection with application users.
mongo_service_id	The service ID of the linked MongoDB cluster that contains the custom user data collection.
database_name	The name of the MongoDB database that contains the custom user data collection.
collection_name	The name of the MongoDB collection that contains custom user data.
user_id_field	The name of a field that contains an application user’s ID value. All user documents in the collection must have this field and no two documents may contain the same user ID.

3

Deploy the Updated Application

Once you have configured the customer user data collection, you can make custom user data available to client applications by deploying your application.

To deploy a draft application with realm-cli:

copy

realm-cli import

To deploy a draft application with automatic GitHub deployment:

copy

git add config.json
git commit -m "Configure and Enable Custom User Data"
git push origin <branch name>

Once the application successfully deploys, MongoDB Realm begins to associate custom data with users. When a user logs in, Realm automatically queries the custom user data collection for a document where the specified User ID Field contains the user’s ID. If a document matches, Realm exposes the data in the document in the custom_data field of that user’s user object.

Access Custom User Data from a Client Application

• iOS SDK
• Android SDK
• Node.js SDK
• React Native SDK

Access Custom User Data

Learn how to access Custom User Data from an iOS application.

Access Custom User Data

Learn how to access Custom User Data from an Android application.

Access Custom User Data

Learn how to access Custom User Data from a Node application.

Access Custom User Data

Learn how to access Custom User Data from a React Native application.

←   Find and View a User Delete or Prevent Users From Accessing a Realm Application  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.