Create and Authenticate Users - Kotlin SDK

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.

To log in with anonymous authentication, create an anonymous credential by calling Credentials.anonymous(), and then pass the generated credential to app.login():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking {
    val anonymousCredentials = Credentials.anonymous()
    val user = app.login(anonymousCredentials)
}

By default, the Kotlin SDK reuses the same anonymous user if that user has not logged out. If you want to create more than one anonymous user, set reuseExisting = false when logging in with additional anonymous credentials:

// Logs in with an anonymous user
val anonUser = app.login(Credentials.anonymous())
// Logs in with a new, different anonymous user
val otherAnonUser =
    app.login(Credentials.anonymous(reuseExisting = false))

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.

To log in with email/password authentication, create an email/password credential by calling Credentials.emailPassword() with the user's registered email and password, and then pass the generated credential to app.login():

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)
}

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.

To log in with JWT authentication, create a JWT credential by calling Credentials.jwt() with the user's JWT, and then pass the generated credential to app.login():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking {
    // Registration is handled by the JWT provider
    val jwtCredentials = Credentials.jwt(jwtToken)
    val user = app.login(jwtCredentials)
}

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.

To log in with API key authentication, create an API Key credential by calling Credentials.apiKey() with the user's API key, and then passing the generated credential to app.login():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking {
    val user = app.login(Credentials.apiKey(key))
}

User API keys are generated automatically and managed by the Kotlin SDK. Learn how to Manage User API Keys - Kotlin SDK.

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.

To log in with Custom Function authentication, pass your custom arguments as a payload to Credentials.customFunction(), and then pass the generated credential to app.login():

// Create custom arguments for your Atlas Function
val customCredentials = Credentials.customFunction(
    payload = mapOf("username" to "bob")
)
val user = app.login(customCredentials)

Learn how to Call an Atlas Function - Kotlin SDK.

You can serialize data for a Custom Function credential using an EJSON encoder. For more information, including examples, refer to EJSON Encoding for Atlas.

Google

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:

1. In the Google Cloud Platform console, create an OAuth 2.0 client ID of type "Web application".

2. Configure your backend App to use that client ID and the associated client secret.

3. Enable OpenID Connect on the backend.

Use Google's official Sign-In for Android to authenticate Google users in your Android application. The following code implements this flow, starting with a method call to loginWithGoogle():

fun loginWithGoogle() {
    val gso = GoogleSignInOptions
        .Builder(GoogleSignInOptions.DEFAULT_SIGN_IN)
        .requestIdToken("YOUR WEB APPLICATION CLIENT ID FOR GOOGLE AUTH")
        .build()
    val googleSignInClient = GoogleSignIn.getClient(activity, gso)
    val signInIntent: Intent = googleSignInClient.signInIntent
    val resultLauncher: ActivityResultLauncher<Intent> =
        // Note: this activity MUST inherit from ComponentActivity or AppCompatActivity to use this API
        registerForActivityResult(ActivityResultContracts.StartActivityForResult())
        { result ->
            val task: Task<GoogleSignInAccount> =
                GoogleSignIn.getSignedInAccountFromIntent(result.data)
            handleSignInResult(task)
        }
    resultLauncher.launch(signInIntent)
}
fun handleSignInResult(completedTask: Task<GoogleSignInAccount>) {
    try {
        if (completedTask.isSuccessful) {
            val account: GoogleSignInAccount? = completedTask.getResult(ApiException::class.java)
            val token: String = account?.idToken!!
            val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
            runBlocking {
                val user = app.login(Credentials.google(token, GoogleAuthType.ID_TOKEN))
            }
        } else {
            Log.e("AUTH", "Google Auth failed: ${completedTask.exception}")
        }
    } catch (e: ApiException) {
        Log.e("AUTH", "Failed to authenticate using Google OAuth: " + e.message);
    }
}

Kotlin Multiplatform (KMP) supports many environments, but this example shows sign-in on the Android platform. For information about signing into a Google account on Apple platforms, refer to the Swift SDK Example.

Facebook

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.

Before you can authenticate users with Facebook, you must set up the authentication flow for your application by following the official Facebook Login for Android Quickstart.

In the login completion handler, get the logged in user's access token from the Facebook LoginResult. Use the access token to create a Facebook credential by calling Credentials.facebook() with the user's access token, and then pass the generated credential to app.login():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
FacebookSdk.setApplicationId(YOUR_FACEBOOK_SDK_APP_ID)
FacebookSdk.sdkInitialize(activity)
val callbackManager = CallbackManager.Factory.create()
LoginManager.getInstance().registerCallback(
    callbackManager,
    object : FacebookCallback<LoginResult> {
        override fun onSuccess(loginResult: LoginResult) {
            // Signed in successfully, forward credentials to MongoDB Realm.
            val accessToken = loginResult.accessToken
            runBlocking {
                val user = app.login(Credentials.facebook(accessToken.token))
            }
        }
        override fun onCancel() {
            Log.v("AUTH", "Cancelled Facebook login")
        }
        override fun onError(exception: FacebookException) {
            Log.e("AUTH", "Failed to authenticate with Facebook: ${exception.message}")
        }
    })

Kotlin Multiplatform (KMP) supports many environments, but this example shows sign-in on the Android platform. For information about signing into a Facebook account on Apple platforms, refer to the Swift SDK Example.

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.

To log in with Apple authentication, create an Apple credential by calling Credentials.apple() with the user's token, and then pass the generated credential to app.login():

val app: App = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking {
    // Registration is handled by Apple
    val appleCredentials = Credentials.apple(idToken)
    val user = app.login(appleCredentials)
}

Kotlin Multiplatform (KMP) supports many environments, but this example shows sign-in on the Android platform. For information about signing in with Apple on Apple platforms, see the Swift SDK Example.

Get a User Access Token

You can get the current access token for a logged-in user with the user.accessToken property:

val token = user.accessToken

If you send requests outside of the SDK, you must include the user's access token with each request and manually refresh the token when it expires. Access tokens expire 30 minutes after a user logs in.

You can get the current refresh token for a logged-in user with the user.refreshToken property, which you can use to request a new access token:

// Gets the current refresh token for the user
fun getRefreshToken(): String {
    return user.refreshToken
}

Configure Refresh Token Expiration

Refresh tokens expire after a set period of time. When the refresh token expires, the access token can no longer be refreshed and the user must log in again.

If the refresh token expires after the realm is open, the device will not be able to sync until the user logs in again. Your sync error handler should implement logic that catches a token expired error when attempting to sync, then redirect users to a login flow.

For information on configuring refresh token expiration, refer to Manage User Sessions in the App Services documentation.