Authenticate Users
On this page
After you initialize an Atlas app connection, you must authenticate a user with an authentication provider. This page describes how to authenticate App Services App users with Atlas Device SDK. Refer to Authenticate & Manage Users in the App Services documentation for more information.
Atlas App Services provides the following built-in authentication providers to log users in and out of a client app:
Anonymous users
Email/password authentication
API key authentication
OAuth 2.0 through Facebook, Google, and Apple ID
Custom JWT
Custom Function
Upon successful login, App Services begins a user session for the user. App Services manages sessions with access tokens and refresh tokens. The SDK automatically supplies the logic to manage tokens and provide them with requests. For more information on managing user sessions and tokens, refer to Manage User Tokens.
Once you have a logged-in user, you can:
Open a synced database with the user's configuration object
Call an Atlas Function as the logged-in user
Log the user out (refer to the Log a User Out section)
You can also log multiple users in to an app simultaneously on a single device. Refer to Multi-User Applications for more information.
Prerequisites
To authenticate users through Atlas App Services, you must have an App Services App with one or more authentication providers enabled.
To set up an App Services App with authentication providers, complete the following:
Enable and configure one or more authentication providers. For more information, refer to Authentication Providers in the App Services documentation.
Tip
You can enable multiple authentication providers. If a user authenticates using more than one method, you can link the user identities for each method to a single user account.
Register and Create a New User Account
Atlas App Services registers a user differently depending on the authentication provider:
If you are using email/password authentication, users must first register and confirm their email and password before they can authenticate.
If you are using Google, Facebook, Apple, or Custom JWT, registration is handled by these third-party services.
If you are using anonymous authentication, those users do not require registration.
Important
Google and Apple Account Deletion Requirements
Google and Apple require that applications listed through their respective App Stores must give any user who creates an account the option to delete the account. Whether you use an authentication method where you must manually register a user, such as email/password authentication, or one that that automatically creates a user, such as Sign-In with Apple, you must implement user account deletion.
Log In a User
Anonymous
Anonymous authentication enables users to log in to your application with short-term accounts that store no persistent personal information. You might use this to allow users to try your app before they sign up for an account or while developing and testing your app. Anonymous users do not require registration. Refer to Anonymous Authentication in the App Services documentation for more information.
Email/Password
The email/password authentication provider enables users to log in to your application with an email username and a password. Refer to Email/Password Authentication in the App Services documentation for more information.
Important
Email/Password Users Require Registration
Email/password authentication requires that you register and then confirm the user-provided email and password before the user can authenticate to an App Services App. Learn how to register email/password users.
Custom JWT
The Custom JWT authentication provider enables users to log in to your application with a custom JSON Web Token (JWT). Registration for JWT authentication is handled by the JWT provider. Refer to Custom JWT Authentication in the App Services documentation for more information.
API Key
The API Key authentication provider enables authenticated non-anonymous users to log in to your application with an API key. Refer to API Key Authentication in the App Services documentation for more information.
User API keys are generated automatically and managed by the SDK. Learn how to Manage User API Keys.
Custom Function
The Custom Function authentication provider enables users to log in to your application using custom authentication logic handled by an Atlas Function. Refer to Custom Function Authentication in the App Services documentation for more information.
The Google authentication provider allows you to authenticate users through their existing Google account using an OAuth 2.0 token. Refer to Google Authentication in the App Services documentation for more information.
Before you can authenticate users with Google, you must set up your application for Google User authentication:
In the Google Cloud Platform console, create an OAuth 2.0 client ID of type "Web application".
Configure your backend App to use that client ID and the associated client secret.
Enable OpenID Connect on the backend.
The Facebook authentication provider allows you to authenticate users through a Facebook app using their existing Facebook account. Refer to Facebook Authentication in the App Services documentation for more information.
Important
Do Not Store Facebook Profile Picture URLs
Facebook profile picture URLs include the user's access token to grant permission to the image. To ensure security, do not store a URL that includes a user's access token. Instead, access the URL directly from the user's metadata fields when you need to fetch the image.
Apple
The Sign-in with Apple authentication provider enables users to log in to your application with a custom token provided by Apple. Refer to Apple ID Authentication in the App Services documentation for more information.
Tip
If you get a Login failed error saying that the token contains
an invalid number of segments, verify that you're passing a UTF-8-encoded
string version of the JWT.
Log In Offline
When your application authenticates a user, it caches the user's credentials. You can check for existing user credentials to bypass the login flow and access the cached user. Use this to open a synced database offline.
Note
Initial login requires a network connection
When a user signs up for your app, or logs in for the first time with an existing account on a client, the device must have a network connection. Checking for cached user credentials lets you open a synced database offline, but only if the user has previously logged in on the device while online.
Log a User Out
Warning
When a user logs out, you can no longer read or write data in any synced databases that the user opened. As a result, any operation that has not yet completed before the initiating user logs out cannot complete successfully and will likely result in an error. Any data in a write operation that fails in this way will be lost.
The log out method:
Deletes locally stored user credentials from the device.
Immediately halts any synchronization to and from the user's synced databases.
For anonymous users, removes the user.
Because logging out halts synchronization, you should only log out after all synced database updates have uploaded to the server.
Observe Authentication Changes
Some SDKs provide platform-idiomatic APIs to observe authentication changes. In other SDKs, you can use platform or language-specific architecture to achieve a similar result without a dedicated API.
Get the Current User
When a user logs in through an App on a device, we cache that App and user
information on the device. You can retrieve the currently logged-in user to
perform app operations without having to log the user in again.
You can continue to work with the current user until the user session expires. When the session expires, the SDK automatically uses a refresh token to start a new session. When the refresh token expires, the SDK cannot start a new session and the user must log in again. You can configure refresh token expiration time in Atlas. For more information, refer to Configure Refresh Token Expiration in the App Services documentation.
If you have multiple users logged in to your app, retrieving a current user returns the last valid user that logged in. It returns null or nil, depending on the language, if there are no logged-in users. Refer to Multi-User Applications for more information.