Docs 菜单
Docs 主页
/ /
Atlas Device SDKs
/ /

创建和验证用户 - Kotlin SDK

在此页面上

  • appservices 用户
  • 先决条件
  • 注册并新建用户账户
  • 登录用户
  • 匿名
  • 电子邮件/密码
  • 自定义 JWT
  • API 密钥
  • 自定义函数
  • Google
  • Facebook
  • Apple
  • 检索当前用户
  • 离线登录
  • 管理用户令牌
  • 获取用户访问令牌
  • 配置刷新令牌到期时间
  • 注销用户
  • 观察身份验证变更

要访问权限Atlas App Services,必须首先使用App Services身份验证提供者对用户进行身份验证。 本页介绍如何使用Realm Kotlin SDK对App Services App用户进行身份验证。 有关详细信息,请参阅App Services文档中的 Authenticate & Manage Users (身份验证和管理用户)。

重要

Google 和 Apple 账号删除要求

Google Apple 要求通过各自 App Store 列出的应用程序必须为创建帐户的任何用户提供删除帐户的选项。无论您使用的是必须手动注册用户的身份验证方法(例如电子邮件/密码身份验证),还是自动创建用户的身份验证方法(例如“通过 Apple 登录”),都必须实现用户帐户删除。

Atlas App Services 提供以下内置身份验证提供程序,用于用户登录和退出客户端应用程序:

  • 匿名用户

  • 电子邮件/密码组合

  • API 密钥

  • 通过 Facebook、Google 和 Apple ID 的 OAuth 2.0

  • 自定义 JWT

  • 自定义函数

成功登录后,App Services 将为用户启动用户会话。App Services 使用访问令牌和刷新令牌托管会话,Kotlin SDK 提供托管令牌并向其提供请求的逻辑。有关管理用户会话和令牌的更多信息,请参阅 App Services 文档中的用户会话

拥有登录用户后,您可以:

您还可以在一台设备上同时让多个用户登录到一个应用程序。 有关更多信息,请参阅管理多用户应用程序 - Kotlin SDK

要通过 Atlas App Services 对用户进行身份验证,您必须在 App Services APP 中启用一个或多个身份验证提供程序。

要使用身份验证提供程序设置 App Services APP,请完成以下操作:

  1. 将您的应用连接到 Atlas App Services

  2. 文档中的“ 启用和配置身份验证提供程序 ”Atlas App Services

提示

您可以启用多个身份验证提供程序。如果用户使用多种方法进行身份验证,则您可以就每种方法将用户身份链接到单个用户帐户。

Atlas App Services 根据身份验证提供程序以不同方式注册用户:

  • 如果您使用电子邮件/密码进行身份验证,则用户必须首先注册并确认其电子邮件和密码,然后才能进行身份验证。

  • 如果您使用的是 Google、Facebook、Apple 或自定义 JWT,注册则由这些第三方服务进行处理。

  • 如果使用匿名身份验证,则无需注册。匿名用户无需注册。

用户首次成功通过身份验证时,Atlas App Services 会自动创建用户对象,其中包含唯一标识符和特定于提供程序的用户元数据。要了解有关 App Services 为 Kotlin SDK 提供的用户对象的详情,请参阅 App Services 文档中的读取用户元数据

要对用户进行身份验证并将其登录到您的App ,请先实例化一个Credentials对象,其中包含与身份验证提供程序关联的档案,然后将其传递给app.login() 。 每个身份验证提供者都对应一个静态辅助方法,用于实例化该身份验证提供者的 Credentials对象。

// Instantiate your App Services App
val app = App.create(YOUR_APP_ID) // Replace this with your App ID
runBlocking {
// Log in the user with the credentials associated
// with the authentication provider
// If successful, returns an authenticated `User` object
val user = app.login(credentials)
// ... work with the user ...
}

如成功,则 app.login() 会返回 User 对象。发生故障时,app.login() 会引发类型为 AppException 的异常。

提示

您可以通过 user.provider 属性获取用于登录用户的身份验证提供程序类型。如果用户当前已登出,则返回最近用于登录用户的提供程序。

匿名身份验证使用户能够使用不存储持久个人信息的短期帐户登录应用程序。 您可以使用它来允许用户在注册帐户之前或在开发和测试您的应用时试用您的应用。 匿名用户无需注册。 有关更多信息,请参阅 文档中的 匿名身份验证 。Atlas App Services

要通过匿名身份验证方式登录,请通过调用 Credentials.anonymous() 创建匿名凭证,然后将生成的凭证传递给 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)
}

默认情况下,如果用户没有注销,Kotlin SDK 会重复使用同一个匿名用户。如果想要创建多个匿名用户,请在使用其他匿名凭证登录时设置 reuseExisting = false

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

电子邮件/密码身份验证提供者可让用户使用电子邮件用户名和密码登录您的应用程序。有关更多信息,请参阅 App Services 文档中的电子邮件/密码身份验证

重要

电子邮件/密码用户需要注册

电子邮件/密码身份验证要求您注册并确认用户提供的电子邮件和密码,然后用户才能对 App Services App 进行身份验证。 了解如何注册电子邮件/密码用户。

要使用电子邮件/密码身份验证登录,请调用 Credentials.emailPassword() 创建电子邮件/密码证书用户的注册电子邮件和密码,然后将生成的凭证传递给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)
}

自定义 JWT 身份验证提供商使用户能够使用自定义 JSON web token (JWT) 登录您的应用程序。 JWT 身份验证的注册由 JWT 提供商处理。 有关更多信息,请参阅 App Services 文档中的自定义 JWT 身份验证

要使用 JSON web token 身份验证登录,请通过调用Credentials.jwt()创建 JSON web token 档案 ,然后将生成的档案传递给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 密钥身份验证提供程序使经过身份验证的非匿名用户能够使用 API 密钥登录您的应用程序。 有关更多信息,请参阅 文档中的 API密钥身份验证 。Atlas App Services

要使用 API 密钥身份验证登录,请调用 Credentials.apiKey() 创建 API 密钥证书使用用户的 API 密钥,然后将生成的凭据传递给 app.login():

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

用户 API 密钥由 Kotlin SDK 自动生成并托管。了解如何管理用户 API 密钥 - Kotlin SDK。

自定义函数身份验证提供商使用户能够使用由 Atlas Function 处理的自定义身份验证逻辑登录到您的应用程序。 有关更多信息,请参阅 App Services 文档中的自定义功能身份验证

要通过自定义函数身份验证方式登录,请将自定义参数作为有效负载传递给 Credentials.customFunction(),然后将生成的凭证传递给 app.login():

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

了解如何调用 Atlas Function - Kotlin SDK

1.9.0 版本中的新增功能

您可以通过 EJSON 编码器序列化自定义函数凭证的数据。有关包括示例在内的详情,请参阅 Atlas 的 EJSON 编码

Google 身份验证提供程序允许您使用 OAuth 2.0令牌通过用户的现有 Google 帐户对用户进行身份验证。 有关更多信息,请参阅 文档中的 Google 身份验证 。Atlas App Services

在使用 Google 对用户进行身份验证之前,必须先将应用程序设置为 Google 用户身份验证:

  1. Google Cloud Platform 控制台 中 ,创建 OAuth2 。0类型为“Web 应用程序”的客户端 ID。

  2. 配置您的后台应用程序,以使用该客户端 ID 和相关的客户端密钥。

  3. 在后端启用 OpenID Connect。

使用 适用于 Android 的 Google 官方登录 对 Android 应用程序中的 Google 用户进行身份验证。以下代码实现了此流程,从对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);
}
}

提示

要了解有关 Google 的 Android 版登录的更多信息,请查看官方的 Google 的 Android 版登录集成指南。

Kotlin Multiplatform (KMP) 支持许多环境,但本示例显示在 Android 平台上登录。 有关在苹果平台上登录 Google 账户的信息,请参阅Swift SDK 示例。

Facebook 身份验证提供者允许您使用用户现有的 Facebook 帐户并通过 Facebook 应用对用户进行身份验证。有关更多信息,请参阅 App Services 文档中的 Facebook 身份验证

在使用 Facebook 对用户进行身份验证之前,必须按照官方 Facebook Login for Android Quickstart 为您的应用程序设置身份验证流程。

在登录完成处理程序中,从 Facebook LoginResult 获取登录用户的访问令牌。使用访问令牌创建 Facebook 凭证,方法是通过用户的访问令牌调用 Credentials.facebook(),然后将生成的凭证传递给 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}")
}
})

重要

请勿存储 Facebook 个人资料图片的 URL

Facebook 个人资料图片 URL 包含用户的访问令牌,用于授予该图像的权限。为了确保安全,请勿存储包含用户访问令牌的 URL。相反,在需要获取图像时,可直接从用户的元数据字段访问 URL。

Kotlin Multiplatform (KMP) 支持多种环境,但本示例显示的是在 Android 平台上的登录。有关在 Apple 平台上登录 Facebook 账户的信息,请参阅Swift SDK 示例

通过 Apple 登录身份验证提供商使用户能够使用 Apple 提供的自定义令牌登录您的应用程序。 有关更多信息,请参阅 App Services 文档中的 Apple ID 身份验证

要使用 Apple 身份验证登录,请通过调用Credentials.apple()创建 Apple 档案 包含用户的令牌,然后将生成的档案传递给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) 支持多种环境,但本示例显示的是在 Android 平台上的登录。有关在 Apple 平台上使用 Apple 登录的信息,请参阅 Swift SDK 示例。

您可以使用 App.currentUser 属性检索当前已登录的用户:

val user = app.currentUser

如果您有多个用户登录到您的应用程序,则返回最后登录的有效用户;如果没有登录用户,则返回null 。 有关更多信息,请参阅管理多用户应用程序 - Kotlin SDK

请注意,currentUser 对象保留在本地存储中,因此即使应用程序在初始身份验证后关闭,您也不需要再次调用 logIn(除非用户已注销或用户会话已过期)。

使用此方法离线登录或在随后应用程序打开时调用 Atlas Function

当您的 Realm 应用程序对用户进行身份验证时,它会缓存该用户的档案。您可以检查是否存在现有用户档案以绕过登录流程并访问已缓存的用户。使用它可离线打开一个 Realm。

注意

初始登录需要网络连接

当用户注册您的应用或使用客户端上的现有帐户首次登录时,客户端必须具有网络连接。通过检查是否存在已缓存的用户档案,您可以离线打开 Realm,但前提是用户之前已在线登录。

// You can only open a synced realm offline if there is a cached user credential. If
// there is no app.currentUser, you must log them in, which requires a network connection.
if (app.currentUser == null) {
app.login(Credentials.emailPassword(email, password))
}
// If the app.currentUser isn't null, you can use the cached credential to open the synced
// realm even if the user is offline.
val user = app.currentUser!!
val realm = Realm.open(config)
// Query the realm we opened, and see that it contains data
val offlineToads: RealmResults<Toad> = realm.query<Toad>().find()
Log.v("After opening a realm offline, offlineToads.size is ${offlineToads.size}")
realm.close()

Realm Kotlin SDK 会自动管理访问令牌,在访问令牌过期时对其进行刷新,并在每次请求中为当前用户提供有效的访问令牌。用户注销后,令牌将被删除。

重要

Realm 仅刷新用户的访问令牌。Realm 不会自动对刷新令牌进行刷新。当刷新令牌过期时,SDK 无法再获取更新的访问令牌,并且在用户再次登录之前设备无法进行同步。

有关用户会话访问和刷新令牌的详情,请参阅 App Services 文档中的用户会话

您可以通过 user.accessToken 属性获取登录用户的当前访问令牌:

val token = user.accessToken

如果在 SDK 外部发送请求,则必须在每个请求中包含用户的访问令牌,并在令牌过期时手动刷新令牌。 访问令牌会在用户登录30分钟后过期。

您可以使用 user.refreshToken 属性获取已登录用户的当前刷新令牌,该令牌可用于请求新的访问令牌:

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

刷新令牌会在设定的时间段后过期。刷新令牌过期后,访问令牌将无法再刷新,用户必须重新登录。

如果刷新令牌在 Realm 打开后过期,则在用户再次登录之前设备无法进行同步。同步错误处理程序应实现在尝试同步时捕获令牌过期错误的逻辑,然后将用户重定向到登录流程。

有关配置刷新令牌过期时间的信息,请参阅 App Services 文档中的管理用户会话

警告

当用户注销时,您无法再在用户已打开的任何已同步 Realm 中读取或写入数据。因此,在发起用户注销之前尚未完成的所有操作均无法成功完成,且可能会导致错误。以此方式失败的写入操作中的所有数据都将丢失。

您可以使用user.logOut() 注销任何用户,无论用于登录的身份验证提供程序如何:

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

user.logOut() 方法:

  • 从设备中删除本地存储的用户凭证。

  • 立即停止与用户 Realm 之间的所有双向同步。

  • 对于匿名用户,删除该用户

由于注销会停止同步,因此您应该仅在所有本地 Realm 更新上传到服务器后再注销。

10.8.0 版本新增

您可以调用 App.authenticationChangeAsFlow(),观察身份验证更改事件的流程。 此流程会发出三种可能状态的 AuthenticationChange 事件,以子类表示:

  • LoggedIn:用户登录应用程序。

  • LoggedOut:用户注销应用程序。

  • Removed:将用户从应用程序中删除,也将用户注销。

这些事件包含一个user属性,该属性提供对已登录、注销或删除的User对象的引用。

// Create a Flow of AuthenticationChange objects
app.authenticationChangeAsFlow().collect {
change: AuthenticationChange ->
when (change) {
is LoggedIn -> proceedToAppActivity(change.user)
is LoggedOut -> proceedToLoginActivity(change.user)
is Removed -> proceedToRemovedUserActivity(change.user)
}
}

后退

管理用户