Navigation

Authentication Triggers

Overview

Authentication Triggers allow you to execute server-side logic whenever a user interacts with an authentication provider. You can use authentication Triggers to implement advanced user management, including storing new user data in your linked cluster, maintaining data integrity upon user deletion, or calling a service with a user’s information when they log in.

Create an Authentication Trigger

To create an authentication trigger in the Realm UI:

  1. Click Triggers under MongoDB Cluster in the left-hand navigation.
  2. Select the Authentication Triggers tab.
  3. Click Add Authentication Trigger in the top right to open the trigger configuration page.
  4. Enter configuration values for the trigger and click Save at the bottom of the page.

To create an authentication Trigger with Realm CLI:

  1. Add an authentication Trigger configuration file to the triggers subdirectory of a local application directory.

    Note

    MongoDB Realm does not enforce specific filenames for Realm Trigger configuration files. However, once imported, MongoDB Realm will rename each configuration file to match the name of the Trigger it defines, e.g. mytrigger.json.

  2. Import the application directory into your application.

    realm-cli import
    

Reference

Authentication Trigger Configuration

Authentication Triggers have the following configuration parameters:

Configuration files for authentication Triggers have the following form:

/triggers/<trigger name>.json
{
   "type": <string>,
   "name": <string>,
   "function_name": <string>,
   "config": {
     "operation_type": <string>,
     "providers": [<string>, ...]
   },
   "disabled": <boolean>
}
Field Description

Trigger Type

type
Required. The type of the trigger. For authentication Triggers, this value should be set to AUTHENTICATION.

Trigger Name

name
Required. The name of the trigger.

Linked Function

function_name
Required. The name of the Realm Function that the Trigger executes whenever it fires. The Trigger passes the authentication event object that caused it to fire as the only argument to this function.

Operation Type

config.operation_type
Required. The authentication operation type that causes the trigger to fire. The operation type must be formatted as a fully-capitalized string, e.g. "LOGIN".

Providers

config.providers

Required. A list of one or more authentication provider types. The Trigger will only listen for authentication events produced by these providers.

The following values are valid:

  • "oauth2-google"
  • "oauth2-facebook"
  • "custom-token"
  • "local-userpass"
  • "api-key"
  • "anon-user"

Authentication Events

Authentication events represent user interactions with an authentication provider. Each event corresponds to a single user action with one of the following operation types:

Operation Type Description
LOGIN Represents a single instance of a user logging in.
CREATE Represents the creation of a new user.
DELETE Represents the deletion of a user.

Authentication event objects have the following form:

{
  "operationType": <string>,
  "providers": <array of strings>,
  "user": <user object>,
  "time": <ISODate>
}
Field Description
operationType The operation type of the authentication event.
providers

The authentication providers that emitted the event.

One of the following names represents each authentication provider:

  • "oauth2-google"
  • "oauth2-facebook"
  • "custom-token"
  • "local-userpass"
  • "api-key"
  • "anon-user"

Note

Generally, only one authentication provider emits each event. When a user linked to multiple providers becomes deleted, the DELETE event for that user will include all linked providers.

user The user object of the user that interacted with the authentication provider.
time The time at which the event occurred.