教程:准备 Android (Kotlin) 应用进行身份验证
这是本教程系列中的第二个教程,演示了如何将适用于 Android 的 Microsoft 身份验证库 (MSAL)添加到 Android (Kotlin) 应用。 MSAL 使 Android 应用程序能够使用 Microsoft Entra 对用户进行身份验证。
在本教程中,你将:
- 添加 MSAL 依赖项。
- 添加配置。
先决条件
- Android Studio
- 请按照教程:注册并配置 Android (Kotlin) 移动应用中的说明操作并在外部租户中注册应用(如果尚未这样做)。
- Android 项目。 如果没有 Android 项目,请创建它。
添加 MSAL 依赖项
要在 Android 项目中添加 MSAL 依赖项,请执行以下步骤:
转到 Android Studio 中的项目,或者创建一个新项目。
打开应用程序的
build.gradle
,并添加以下依赖项:allprojects { repositories { //Needed for com.microsoft.device.display:display-mask library maven { url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1' name 'Duo-SDK-Feed' } mavenCentral() google() } } //... dependencies { implementation 'com.microsoft.identity.client:msal:5.+' //... }
在
build.gradle
配置中,为项目依赖项定义存储库。 它包括 Azure DevOps 中com.microsoft.device.display:display-mask
库的 Maven 存储库 URL。 此外,它还利用 Maven Central 和 Google 存储库。 依赖项部分指定 MSAL 版本 5 和潜在其他依赖项的实现。在 Android Studio 中,选择“文件”>“将项目与 Gradle 文件同步”。
添加配置
请通过 JSON 配置设置将所需的租户标识符(例如应用程序(客户端)ID)传递到 MSAL SDK。
请使用以下步骤创建配置文件:
在 Android Studio 的项目窗格中,导航到 app\src\main\res。
右键单击“res”,选择“新建”>“目录”。 输入
raw
作为新目录名称,然后选择“确定”。在 app\src\main\res\raw 中,创建一个名为
auth_config_ciam_auth.json
的新 JSON 文件。在
auth_config_ciam_auth.json
文件中,添加以下 MSAL 配置:{ "client_id" : "Enter_the_Application_Id_Here", "authorization_user_agent" : "DEFAULT", "redirect_uri" : "Enter_the_Redirect_Uri_Here", "account_mode" : "SINGLE", "authorities" : [ { "type": "CIAM", "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/" } ] }
JSON 配置文件指定 Android 应用程序的各种设置。 它包括客户端 ID、授权用户代理、重定向 URI 和帐户模式。 此外,它还定义用于身份验证的颁发机构,并指定类型和颁发机构 URL。
将以下占位符替换为从 Microsoft Entra 管理中心获取的租户值:
- 查找
Enter_the_Application_Id_Here
并将其替换为之前注册的应用的应用程序(客户端)ID。 Enter_the_Redirect_Uri_Here
并将其替换为之前在添加平台重定向 URL 时下载的 Microsoft 身份验证库 (MSAL) 配置文件中 redirect_uri 的值。Enter_the_Tenant_Subdomain_Here
并将其替换为目录(租户)子域。 例如,如果租户主域为contoso.onmicrosoft.com
,请使用contoso
。 如果不知道租户子域,请了解如何读取租户详细信息。
- 查找
打开 /app/src/main/AndroidManifest.xml 文件。
在AndroidManifest.xml中,将以下数据规范添加到意向筛选器:
<data android:host="ENTER_YOUR_PROJECT_PACKAGE_NAME_HERE" android:path="/ENTER_YOUR_SIGNATURE_HASH_HERE" android:scheme="msauth" />
查找占位符:
- ENTER_YOUR_PROJECT_PACKAGE_NAME_HERE,并将其替换为 Android 的项目包名称。
- ENTER_YOUR_SIGNATURE_HASH_HERE,并将其替换为之前添加平台重定向 URL 时生成的签名哈希。
使用自定义 URL 域(可选)
使用自定义域可完全标记身份验证 URL。 从用户的角度来看,用户在身份验证过程中仍留在你的域中,而不是重定向到 ciamlogin.com 域名。
通过以下步骤使用自定义域:
使用为外部租户中的应用启用自定义 URL 域中的步骤为外部租户启用自定义 URL 域。
打开 auth_config_ciam_auth.json 文件:
- 将
authority_url
属性的值更新为 https://Enter_the_Custom_Domain_Here/Enter_the_Tenant_ID_Here。 将Enter_the_Custom_Domain_Here
替换为你的自定义 URL 域,并将Enter_the_Tenant_ID_Here
替换为你的租户 ID。 如果没有租户 ID,请了解如何读取租户详细信息。 - 添加值为 [Enter_the_Custom_Domain_Here] 的
knownAuthorities
属性。
- 将
对 auth_config_ciam_auth.json 文件进行更改后,如果自定义 URL 域为 login.contoso.com 且租户 ID 为 aaaabbbb-0000-cccc-1111-dddd2222eeee,则文件应类似于以下代码片段:
{
"client_id" : "Enter_the_Application_Id_Here",
"authorization_user_agent" : "DEFAULT",
"redirect_uri" : "Enter_the_Redirect_Uri_Here",
"account_mode" : "SINGLE",
"authorities" : [
{
"type": "CIAM",
"authority_url": "https://login.contoso.com/aaaabbbb-0000-cccc-1111-dddd2222eeee",
"knownAuthorities": ["login.contoso.com"]
}
]
}
创建 MSAL SDK 实例
要初始化 MSAL SDK 实例,请使用以下代码:
private suspend fun initClient(): ISingleAccountPublicClientApplication = withContext(Dispatchers.IO) {
return@withContext PublicClientApplication.createSingleAccountPublicClientApplication(
this@MainActivity,
R.raw.auth_config_ciam_auth
)
}
该代码以异步方式初始化单个帐户公共客户端应用程序。 它使用提供的身份验证配置文件并在 I/O 调度程序上运行。
确保包含 import 语句。 Android Studio 应该会自动为你包含 import 语句。