Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Device SDKs
/
Kotlin SDK
/
Manage Users

Manage Email/Password Users - Kotlin SDK

On this page

  • Register a New User
  • Confirm a New User's Email Address
  • Retry User Confirmation Methods
  • Resend a User Confirmation Email
  • Retry a User Confirmation Function
  • Reset a User's Password
  • Send a Password Reset Email
  • Run a Password Reset Function
  • Log In or Log Out a User

When you enable the email/password provider in your Atlas App Services App, you can handle user authentication from client code by registering and logging in new user.

Register a New User

To register a new user, pass a user-provided email and password to app.emailPasswordAuth.registerUser():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interactions
    app.emailPasswordAuth.registerUser(email, password)
}

Confirm a New User's Email Address

When you enable the email/password provider, in App Services, you select a confirmation method. The App Services email/password confirmation service provides a token and token ID that you can get to the user through email or a custom Atlas Function. To confirm the user, provide that token and tokenId to app.emailPasswordAuth.confirmUser():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interactions
    app.emailPasswordAuth.confirmUser(token, tokenId)
}

After you confirm the user, you can proceed to login with email/password credentials.

Retry User Confirmation Methods

The SDK provides methods to resend user confirmation emails or retry custom confirmation methods.

Resend a User Confirmation Email

Resend a confirmation email. The confirmation tokens in each URL expire after 30 minutes. If a user does not follow the link and confirm within that period, they must request a new confirmation email.

To resend a user confirmation email, provide the user's email address to app.emailPasswordAuth.resendConfirmationEmail():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interaction
    app.emailPasswordAuth.resendConfirmationEmail(email)
}

Retry a User Confirmation Function

To retry a custom user confirmation function, provide the user's email address to app.emailPasswordAuth.retryCustomConfirmation():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interaction
    app.emailPasswordAuth.retryCustomConfirmation(email)
}

Reset a User's Password

Resetting a user's password is a multi-step process.

  1. In your client app, you provide a UI for the user to reset their password. Your App Services App can then send an email or run a custom function to confirm the user's identity.

  2. After confirming the user's identity, you can complete the password reset request.

  3. After the password reset is complete, the user can log in using the new password.

For more information about how to set your preferred password reset method, refer to the App Services Email/Password Authentication documentation.

Send a Password Reset Email

To send password reset emails to confirm the user's identity, you must configure your App to send a password reset email.

To begin the password reset process, call app.emailPasswordAuth.sendResetPasswordEmail() with the user's email. App Services sends an email to the user that contains a unique URL. The user must visit this URL within 30 minutes to confirm the reset.

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interaction
    app.emailPasswordAuth.sendResetPasswordEmail(email)
}

After the user has visited the URL from the password reset email, call app.emailPasswordAuth.resetPassword() with the user's email, the new password, and the token and tokenId provided in the unique URL.

If the user does not visit the URL from the password reset email within 30 minutes, the token and tokenId expire. You must begin the password reset process again.

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interactions
    app.emailPasswordAuth.resetPassword(token, tokenId, newPassword)
}

Run a Password Reset Function

When you configure your app to run a password reset function, you define the function that should run when you call app.emailPasswordAuth.callResetPasswordFunction() from the SDK. This function can take a username, a password, and any number of additional arguments. You can use these arguments to specify details like security question answers or other challenges that the user should pass to successfully complete a password reset.

You might prefer to use a custom password reset function when you want to define your own password reset flows. For example, you might send a custom password reset email from a specific domain. Or you might use a service other than email to confirm the user's identity.

On the App Services side, you define the custom password reset function that runs when you call this method. That function can return one of three possible statuses:

  • fail

  • pending

  • success

A fail status is treated as a ServiceException error by the SDK. The SDK callResetPasswordFunction() does not return a pending or success status to the client.

Server-Side Pending Case

Your App Services password reset function may return pending if you want the user to take some additional step to confirm their identity. However, that return value is not passed to the SDK's callResetPasswordFunction(), so your client app must implement its own logic to handle a pending status.

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interaction
    app.emailPasswordAuth.callResetPasswordFunction(email, newPassword)
}

Your server-side function might send an email using a custom email provider. Or you may use SMS to confirm the user's identity via text message.

You have access to a token and tokenId in the App Services password reset function context. If you pass this information from your App Services password reset function, you can pass these values back to your app using deep links in Android or universal links in iOS. Then, your client application can call resetPassword() to complete the password reset flow.

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interactions
    app.emailPasswordAuth.resetPassword(token, tokenId, newPassword)
}

Server-Side Success Case

If your App Services password reset function does additional validation within the function, or if you have validated the user's identity prior to attempting to reset the password, you may configure the App Services function to return success. However, that return value is not passed to the SDK's callResetPasswordFunction(), so your client app must implement its own logic to handle a success status.

Calling the function in this example performs the entire password reset process.

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking { // use runBlocking sparingly -- it can delay UI interaction
    app.emailPasswordAuth.callResetPasswordFunction(email, newPassword, args)
}

Log In or Log Out a User

After you register a user, it is a separate step to log the user in.

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking {
    val emailPasswordCredentials = Credentials.emailPassword(email, password)
    val user = app.login(emailPasswordCredentials)
}

You can log out an authenticated user.

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking {
    val user = app.login(credentials)
    // ... work with logged-in user ...
    // Ensure all local updates are uploaded
    // before logging out
    user.logOut()
}

Back

Create & Authenticate Users

Next

Link User Identities