Navigation

Custom Function Authentication

Overview

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.

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.

Configuration

1
2

Enable the Provider

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.

3

Define the Authentication Function

The authentication function must return a string ID value that uniquely identifies the user. Realm uses this value to lookup 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 string, Realm throws an error and does not create or authenticate a user.

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.

Example

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 appication’s authentication function queries the 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.

exports = async function(loginPayload) {
  // Get a handle for the app.users collection
  const users = context.services
    .get("mongodb-atlas")
    .db("app")
    .collection("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();
  }
};
4

Deploy the Updated Application

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-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, you will be able to create and log in as a Custom Function user from a client application.

1

Export Your Realm Application

You can set up and enable the Custom Function authentication provider through realm-cli or automatic GitHub deployment. To configure the provider, 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:

TODO
2

Define the Authentication Function

The authentication function must return a string ID value that uniquely identifies the user. MongoDB Realm uses this value to lookup 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 string, MongoDB Realm throws an error and does not create or authenticate a user.

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). MongoDB Realm automatically generates a unique id for Custom Function users when it creates them.

To create the authentication function, write the function code and then follow the steps in Define a Function to add it to your application.

Example

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

exports = async function(loginPayload) {
  // Get a handle for the app.users collection
  const users = context.services
    .get("mongodb-atlas")
    .db("app")
    .collection("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();
  }
};
3

Add a Provider Configuration File

To configure the Custom Function authentication provider, create a new authentication provider configuration file named custom-function.json in the auth_providers directory and set the value of config.authFunctionName the name of the authentication function:

/auth_providers/custom-function.json
{
    "name": "custom-function",
    "type": "custom-function",
    "config": {
      "authFunctionName": "<Authentication Function Name>"
    },
    "disabled": false
}
4

Deploy the Updated Application

Once you have created the authentication function and configured the provider, you can make Custom Function authentication available to client applications by deploying your application.

To deploy a draft application with realm-cli:

TODO

To deploy a draft application with automatic GitHub deployment:

TODO

Once the application successfully deploys, you will be able to create a user and log in with the Custom Function provider from a client application.

Summary

  • 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.