Custom Function Authentication

The Custom Function authentication provider allows you to use a Realm Function to implement your own user authentication logic or flexibly integrate an external authentication system. You can use the Custom Function provider to integrate with any authentication system as long as the system maintains a unique ID value for each user.

The authentication function is a Realm Function that you define to handle authentication logic for users that log in with the Custom Function provider. You can use the function to coordinate with an external authentication system and/or use data that you store in MongoDB to identify and authenticate users.

Important With Circle IconCreated with Sketch.Important
Validate and Authenticate Custom Function Users

Realm does not perform any data validation or authentication checks for the Custom Function provider. Make sure that you validate incoming data and that your authentication system performs appropriate authentication checks, such as requiring a password, two factor authentication, or a single sign-on token.


You can set up and enable the Custom Function authentication provider in the Realm UI. To get to the settings page, click App Users in the left navigation menu, select the Providers tab, and then click Custom Function Authentication.


To create new users and allow them to log in, you must enable the Custom Function provider. To do so, set the Provider Enabled toggle to On.


The authentication function must return a string ID value or an object containing a string ID value that uniquely identifies the user. MongoDB Realm uses this value to look up an existing Realm user and automatically creates a new user if it does not match an existing user. If the function does not return a valid return value, MongoDB Realm throws an error and does not create or authenticate a user.

Valid return values options include:

Beaker IconExample

A string ID value that uniquely identifies the user

return "5f650356a8631da45dd4784c"

An object that contains a string ID value that uniquely identifies the user

return { "id": "5f650356a8631da45dd4784c" }
return { "id": "5f650356a8631da45dd4784c", "name": "James Bond" }
Important With Circle IconCreated with Sketch.Important
Realm Generates New User ID Values

The ID value that you return from the authentication function is not the internal Realm user id (i.e. the value that %%user and context.user resolve to). Realm automatically generates a unique id for Custom Function users when it creates them.

To define a new authentication function, click the Function dropdown and select New Function.

Beaker IconExample

An application implements a Custom Function authentication provider that stores user data in the app.users MongoDB collection. The app lets users log in by specifying their username but does not require a password or any other type of authentication.

The application's authentication function queries the app.users collection for an existing user with the specified username. If the user already exists, the function returns their stored id value. If the user does not exist, the function stores a new user document in the collection and returns that document's id value.

Info With Circle IconCreated with Sketch.Note

Realm does not automatically create an app.users collection for your application. You can use your custom function with an external authentication system and/or data that you store in a MongoDB collection to identify and authenticate users.

exports = async function(loginPayload) {
// Get a handle for the app.users collection
const users =
// Parse out custom data from the FunctionCredential
const { username } = loginPayload;
// Query for an existing user document with the specified username
const user = await users.findOne({ username });
if (user) {
// If the user document exists, return its unique ID
return user._id.toString();
} else {
// If the user document does not exist, create it and then return its unique ID
const result = await users.insertOne({ username });
return result.insertedId.toString();

Once you have written and saved the authentication function, you can make Custom Function authentication available to client applications by deploying your application. To deploy a draft application from the Realm UI:

  1. Click Deploy in the left navigation menu
  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, you will be able to create and log in as a Custom Function user from a client application.

For code examples that demonstrate how to register and log in using Custom Function authentication, see the documentation for the Realm SDKs:

To register or log in a Custom Function user from the iOS Client SDK, see the iOS SDK guide to Custom Function authentication.

  • Custom Function authentication allows you to define your authentication process in a Realm Function.
  • The Realm Function that you use for authentication should return a unique ID for each user based on the information passed from the client SDK.
Give Feedback