Using MongoDB Atlas as a Custom Database

TL;DR: In this article, you will learn how to set up MongoDB Atlas as a custom database in your Auth0 account. First, you will learn how to configure your custom database to migrate users to Auth0 (which will end up improving the security of your app and the privacy of your users), then you will learn how to keep your MongoDB Atlas cluster up to date.

Preparing the MongoDB Atlas Cluster
If you already have a MongoDB Atlas database cluster that you would like to use, feel free to skip to the Whitelisting IP addresses section. However, if you need to set up a test environment, follow the instructions described here. go through MongoDB online training for more techniques

To create a new MongoDB Atlas cluster, head to their website and use the get started free form to create a new account (or you can sign into an existing one if you prefer). When you get into your MongoDB Atlas dashboard, click on the build a cluster button. After clicking on it, the dashboard will present you a form that you can fill in like this:

Cloud Provider & Region: AWS, N. Virginia (us-east-1)
Cluster Tier: M0 (Shared RAM, 512 MB Storage)
Additional Settings: MongoDB 4.0, No Backup
Cluster Name: Cluster0
These settings will give you a brand new cluster that is free forever (but be aware that this cluster is not good enough for production, just for testing). So, after filling in this form, click on the create cluster button to finish the process.

How to Create a MongoDB User
Now that you have your MongoDB cluster up and running, the next thing you will do is to create a database user to access it. To do so, head to the Security tab of your cluster and click on the Add New User button. When you click on this button, the dashboard will ask you to:

Enter a username: Here you can add something like auth0-custom-db-user.
Enter a password: Here you will have to define a password for this user (you can use the Autogenerate secure password to help you on this).
Set User Privileges: Here you will have to choose the Read and write to any database option.

After filling in this form, click on the Add User button. The process might need a few seconds to take effect.

Whitelisting IP addresses
As explained by the docs, MongoDB Atlas only allows client connections to the cluster from entries in the project’s whitelist. As such, you will need to go to the IP Whitelist section of the Security tab of your cluster and add the IP addresses that Auth0 uses. When you reach this section, click on the Add IP Address button and use the form to add addresses. You will need to use this form to add all the ip addresses that Auth0 uses, one by one.

Note that, depending on where you chose to create your tenant, the set of IP addresses will vary. To confirm what addresses you will need to add, please, check this resource. MongoDb online course helps you to learn more effectively.

For example, at the time of writing, Auth0 was using the following IP addresses for tenants based on their US region:

35.167.74.121
35.166.202.113
35.160.3.103
54.183.64.135
54.67.77.38
54.67.15.170
54.183.204.205

Preparing the Database
If you already have a database with users and passwords, you can skip this section. Otherwise, you will have to add a collection into your cluster with credentials, so that you can test the integration between Auth0 and Atlas. To do so, you will need to use a MongoDB client application (like MongoDB shell or MongoDB Compass) to connect to your cluster and to create this collection.

To connect your client application to Atlas, open your cluster details in the dashboard and click on the Connect button. When you click on this button, Atlas will show you three options:

Connect with the Mongo Shell: You can choose this one if you feel comfortable on the terminal.
Connect Your Application: You would choose this one if you were making a custom app connect to the cluster (not the case here).
Connect with MongoDB Compass: You can choose this one if you prefer using MongoDB Compass.
Follow the instructHow to Use Auth0 Custom Databases and Migrate Users
After preparing your MongoDB Atlas cluster, you are now ready to configure Auth0 to use this cluster as a custom database. To achieve that, you will need to sign into your Auth0 dashboard, and head to its Database Connections section.

Note: If you don’t have one yet, you can sign up for a free Auth0 account here.

Inside this section, click on the Create a DB Connection button. Then, on the New Database Connection form, insert a name to your new connection (something meaningful like atlas-custom-db) and click on the Create button.

After creating the database connection, head to its Custom Database section and turn on the Use my own database option. Clicking on it will make the area below this option available. As you can see there, Auth0 will enable you to customize how the integration will work on different scenarios: login, create, verify, change password, get user, and delete.

As the goal now is to import users from MongoDB Atlas into Auth0, you will head back to the Settings tab of your custom connection and click on the Import Users to Auth0 option.

There are a few important things that you must understand about this code:

The script you are defining is actually a function that receives three parameters: email, password, and callback. You will use the first two parameters (email and password) to validate the user against your legacy database. Then, you will use the callback parameter to end this function (successfully or not).

This script depends on version 3.1.4 of the mongodb library. You need this specific version because the others available on Auth0 do not support MongoDB Seed Lists (a feature used by Atlas).

This script defines five constants that you will have to update: dbUser, dbPwd, dbHost, dbName, and usersCollection. The first two (dbUser and dbPwd) are the credentials of the database user you created earlier, the latter (usersCollection) is the name of the collection where you inserted application users, and the other two (dbHost and dbName) are the identifier of your cluster and database on MongoDB Atlas. Make sure to update these constants accordingly.

Note: The dbHost constant will look like cluster0-a1ig3.mongodb.net.

After connecting to your cluster, this function gets a reference to the user collection and uses it to issue a query to findOne user with the email and password passed to this function. If an error occurs, or if no user with these credentials is found, the function ends with an error (i.e., the authentication process fails). Otherwise, the function creates a profile object and passes it to the callback function.
Passing a profile as the second argument to the callback function will make the login script end successfully. That is, if you call the callback function with a profile, your user will successfully log in, and its details will migrate from your Atlas cluster to Auth0.ions on one of these options to connect to the cluster. After connecting to it, you will have to create a database on it (you can call it auth0-integration), and you will have to create a users collection inside this database.

If you are on MongoDB Compass, you can use the Create Database button to achieve that. If you are on MongoDB Shell, you can issue use auth0-integration to create the database.

Once the database is created, you can start adding application users to your cluster.
How to Use Auth0 Custom Databases and Migrate Users
After preparing your MongoDB Atlas cluster, you are now ready to configure Auth0 to use this cluster as a custom database. To achieve that, you will need to sign into your Auth0 dashboard, and head to its Database Connections section.

Note: If you don’t have one yet, you can sign up for a free Auth0 account here.

As the goal now is to import users from MongoDB Atlas into Auth0, you will head back to the Settings tab of your custom connection and click on the Import Users to Auth0 option.

There are a few important things that you must understand about the code:

This script depends on version 3.1.4 of the mongodb library. You need this specific version because the others available on Auth0 do not support MongoDB Seed Lists (a feature used by Atlas).

Note: The dbHost constant will look like cluster0-a1ig3.mongodb.net.

Custom Databases without User Migration
Another alternative that you have while using Auth0 custom databases is to keep your users’ data in your own servers (in other words: to avoid user migration). This alternative gives you better control over this data but, on the other hand, gives you also the burden of having to deal with the security and privacy of your users’ data.

After considering the pros and cons of this alternative, if you still feel like this is the way to go, Auth0 can help you keep the data in your own data stores. To achieve this, you will need to start by opening the Settings tab of your database connection (on the Auth0 dashboard) and ticking off the Import Users to Auth0 checkbox. Then, if you go to the Custom Database tab one last time, you will have to implement each one of the authentication steps: login, create, verify, change password, get user, and delete.

#mongodbcourse #mongodbtraining #mongodbonlinetraining #mongodbonlinecourse #mongodbfullcourse