Authentication Triggers

On this page

Create an Authentication Trigger

Configuration
Authentication Events
Example
Additional Examples

Atlas Device Sync, Atlas Edge Server, Data API, and HTTPS Endpoints are deprecated. Refer to the deprecation page for details.

The Triggers documentation is moving to the Atlas docs. Please refer to the Triggers documentation in its new location.

An authentication trigger fires when a user interacts with an authentication provider. You can use authentication triggers to implement advanced user management. Some uses include:

Storing new user data in your linked cluster
Maintaining data integrity upon user deletion
Calling a service with a user's information when they log in.

Create an Authentication Trigger

To open the authentication trigger configuration screen in the Atlas App Services UI, click Triggers in the left navigation menu, click Create a Trigger, and then select the Authentication tab next to Trigger Type.

Configure the trigger and then click Save at the bottom of the page to add it to your current deployment draft.

An example of a configured authentication trigger in the UI

click to enlarge

To create an authentication trigger with App Services CLI:

Add an authentication trigger configuration file to the triggers subdirectory of a local application directory.
Note
App Services does not enforce specific filenames for Atlas Trigger configuration files. However, once imported, App Services will rename each configuration file to match the name of the trigger it defines, e.g. mytrigger.json.
Deploy the trigger:
```
appservices push
```

Configuration

Authentication Triggers have the following configuration options:

Field	Description
Trigger Type	The type of the trigger. For authentication triggers, set this value to `AUTHENTICATION`.
Action Type	The authentication operation type that causes the trigger to fire.
Providers	A list of one or more authentication provider types. The trigger only listens for authentication events produced by these providers.
Event Type	Choose what action is taken when the trigger fires. You can choose to run a function or use AWS EventBridge.
Function	The name of the function that the trigger executes when it fires. An authentication event object causes the trigger to fire. This object is the only argument the trigger passes to the function.
Trigger Name	The name of the trigger.

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: `"anon-user"` `"local-userpass"` `"api-key"` `"custom-token"` `"custom-function"` `"oauth2-facebook"` `"oauth2-google"` `"oauth2-apple"` Note Generally, only one authentication provider emits each event. However, you may need to delete a user linked to multiple providers. In this case, the `DELETE` event for that user includes all linked providers.
`user`	The user object of the user that interacted with the authentication provider.
`time`	The time at which the event occurred.

Example

An online store wants to store custom metadata for each of its customers in Atlas. Each customer needs a document in the store.customers collection. Then, the store can record and query metadata in the customer's document.

The collection must represent each customer. To guarantee this, the store creates an Authentication Trigger. This Trigger listens for newly created users in the email/password authentication provider. Then, it passes the authentication event object to its linked function, createNewUserDocument. The function creates a new document which describes the user and their activity. The function then inserts the document into the store.customers collection.

Trigger Configuration

{
  "type": "AUTHENTICATION",
  "name": "newUserHandler",
  "function_name": "createNewUserDocument",
  "config": {
    "providers": ["local-userpass"],
    "operation_type": "CREATE"
  },
  "disabled": false
}

createNewUserDocument

exports = async function(authEvent) {
  const mongodb = context.services.get("mongodb-atlas");
  const customers = mongodb.db("store").collection("customers");
  const { user, time } = authEvent;
  const isLinkedUser = user.identities.length > 1;
  if(isLinkedUser) {
    const { identities } = user;
    return users.updateOne(
      { id: user.id },
      { $set: { identities } }
    )
  } else {
    return users.insertOne({ _id: user.id, ...user })
     .catch(console.error)
  }
  await customers.insertOne(newUser);
}

Additional Examples

For additional examples of Triggers integrated into an App Services App, checkout the example Triggers on Github.

Back

Database Triggers

Scheduled Triggers