Create an App User
On this page
Overview
Atlas App Services provides various authentication providers to log users into your app. For most providers, App Services automatically creates a user account the first time a user authenticates through the provider. The only exception is email/password user authentication, which requires registering and confirming a user before the user can authenticate.
Tip
Apple Account Deletion Requirements
Apple requires that applications distributed through the App Store must give any user who creates an account the option to delete the account. Whether that app uses an authentication method where you must manually register a user, such as email/password authentication, or one that automatically creates a user, such as Sign-In with Apple, an app distributed through the App Store must implement user account deletion.
Identity
When you first log in with an authentication provider, App Services creates a user object that contains a unique identity ID and provider-specific metadata about the user.
Link to Existing Accounts
A single user object can have more than one identity. You can use the Realm SDKs to link identities to existing user accounts. This allows users to log in to a single account with more than one provider. For more information, see the documentation on linking identities for your preferred SDK:
Create an Email/Password User
When you use email/password user authentication, you must first register a user, which creates the user object. You can register users in your client application using your preferred SDK or you can manually create email/password users.
After registering the user, you must confirm the user before they can authenticate.
Create an Email/Password User in the SDK
Each SDK offers an API that enables you to register an email/password user. After registering the user, you must confirm the user before the they can authenticate. For code examples that demonstrate how to manage email/password users in the client application, see the documentation for the Realm SDKs:
Manually Create an Email/Password User
You can create a new Email/Password user from the App Services UI, CLI, or Admin API. Manually-created users bypass any configured user confirmation flows.
Tip
Manually creating a user can be useful for testing and debugging your application in development.
Select App Users from the left navigation menu.
Click the Add New User button.
Specify an email address and password for the new user.
Note
The Email/Password authentication provider requires passwords to be between 6 and 128 characters long.
Click Create.
Note
You can also create API keys that applications use to connect to your App. Although API Keys are not associated with a single user, the Users tab lists them. To learn more about API keys, see API Key Authentication.
To create a new email/password user, call appservices users create and
specify --type=email. The CLI will prompt you for your App ID as well
as the new user's email and password.
appservices users create --type=email
You can also specify the arguments when you call the program:
appservices users create --type=email \ --app=<Your App ID> \ --email=<User's Email Address> \ --password=<User's Password>
Note
The Email/Password authentication provider requires passwords to be between 6 and 128 characters long.
To create a new email/password user, create a POST request
in the following format. You must specify the user credentials
in the request body and the Group and App ID in the request URL.
curl --request POST \ --header 'Authorization: Bearer <access_token>' \ --data '{ "email": "<string>", "password": "<string>" }' \ https://services.cloud.mongodb.com/api/admin/v3.0/groups/<groupId>/apps/<appId>/users
Note
The Email/Password authentication provider requires passwords to be between 6 and 128 characters long.
Confirm a User
You must confirm the email address of new Email/Password users before they are permitted to log into App Services. The exact method of confirmation depends upon your provider configuration, but typically involves a handshake process between the user and your application. You can read more about Email/Password user confirmation at Email/Password Confirmation.
Sometimes, users are unable to complete the confirmation process. For example:
An overzealous spam filter might block App Services email confirmation emails.
A proxy or web blocker could prevent a user from activating the
confirmUserclient SDK function via the client application.An implementation error could cause the client application's user confirmation page to fail for specific use cases.
To help you work around cases like this, you can confirm users manually using the App Services UI or the Admin API:
To confirm a pending email/password user in the UI:
Select App Users from the left navigation menu.
Under the Users tab, select the PENDING button.
Find the user in the list and click on the ellipsis (
...).Select the Confirm User option from the context menu that appears.
If the operation succeeds, the banner at the top of the App Services admin console should display a confirmation message. The user's User Status changes from Pending Confirmation to Pending User Login.
A manually-confirmed user continues to appear in the PENDING
user list until they log in to your application for the first time, at
which point App Services moves them into the list of confirmed users and
transitions their User Status to confirmed.
To confirm a pending email/password user using the Admin API, create
a POST request in the following format. You must specify the Group
ID, App ID, and email address.
curl --request POST \ --header 'Authorization: Bearer <access_token>' \ https://services.cloud.mongodb.com/api/admin/v3.0/groups/<groupId>/apps/<appId>/user_registrations/by_email/<email>/confirm
Re-run the User Confirmation Workflow
A few circumstances can lead to incomplete Email/Password user confirmation workflows:
An email is caught by a spam filter, not delivered due to a bug, or accidentally deleted by a prospective App Services user.
A custom confirmation function is unable to communicate with an unconfirmed user due to a bug or oversight.
An unconfirmed user forgot to visit their confirmation link within 30 minutes of receiving their login tokens, and the tokens expired.
Users caught in this situation appear stuck in an unconfirmed state. Since an existing account has their email registered to it, users cannot create a new account with the same email address. Also, they cannot log into an account that is not confirmed.
Applications that use the built-in email confirmation service of App Services
can use the resendConfirmationEmail Client SDK method to send a new
email with a new confirmation link to the user, allowing them to confirm
their account and log in. Calling this method will result in an error by
any application using a confirmation flow other than send a
confirmation email.
There is no such specific method to re-run a custom confirmation function. Instead, App Services has a method to trigger a re-run of whatever the current Email/Password user confirmation workflow happens to be. You can manually re-run the currently selected user confirmation flow using the App Services UI or the App Services Admin API:
To re-run the confirmation workflow for a user in the UI:
Select App Users from the left navigation menu.
Under the Users tab, select the PENDING button.
Find the user in the list and click on the ellipsis (
...).Select the Run user confirmation option from the context menu that appears.
Select the Run User Confirmation button in the dialogue box that appears.
If the operation succeeds, the banner at the top of the App Services admin console should display a confirmation message. The user's User Status changes from Pending Confirmation to Pending User Login. Once the user logs in, they will move into the list of active users automatically.
If the re-run fails or the user's tokens expire again, you can re-run the confirmation function as many times as necessary.
To re-run the confirmation workflow for a user using the Admin API, create a
POST request in the following format. You must specify the Group ID, App ID,
and email address.
curl --request POST \ --header 'Authorization: Bearer <access_token>' \ https://services.cloud.mongodb.com/api/admin/v3.0/groups/<groupId>/apps/<appId>/user_registrations/by_email/<email>/run_confirm
Summary
For all providers except for Email/Password authentication, App Services automatically creates a user object the first time a user authenticates.
You can log in to a single account with more than one provider by using the Realm SDKs to link identities.
The Email/Password authentication provider requires users to create an account the first time they connect to your App.
Email/Password users must be confirmed manually through the App Services UI or Admin API.
Users caught in an incomplete Email/Password confirmation workflow must re-run the confirmation through the App Services UI or Admin API.