适用于 Android 的Microsoft身份验证库

适用于 Android 的 Microsoft 身份验证库 （MSAL） 是一个库，它使 Android 应用程序能够使用 Microsoft 标识平台（以前Azure Active Directory）对用户进行身份验证，并使用 OAuth2 和 OpenID Connect 协议访问受保护的 Web API。 MSAL Android 使开发人员能够从Microsoft 标识平台获取安全令牌，以对用户进行身份验证，并访问其基于 Android 的应用程序的安全 Web API。

MSAL Android 支持多种身份验证方案，例如单一登录（SSO）、条件访问和中转身份验证。 它允许你轻松定位多个标识，包括Microsoft Entra ID（工作和学校帐户）、Microsoft帐户（Outlook.com、hotmail.com 和其他几个），或Azure AD B2C（社交和本地帐户）。

此处的指南旨在记录与 MSAL Android 相关的常见功能。 如果你想进一步了解如何开始使用 Microsoft Entra ID、Microsoft 帐户或 Azure AD B2C，请参阅 Microsoft 标识平台文档。如果你想获取有关 Microsoft Graph API 的更多信息，请参阅 Microsoft Graph 文档。

MSAL 中的原生身份验证支持

MSAL Android 还允许你在移动应用程序中使用端到端可自定义流实现本机身份验证体验。 使用本机身份验证时，用户无需离开应用即可完成丰富的本机移动优先注册和登录旅程。 本机身份验证功能仅适用于 客户外部 ID 上的移动应用。

从Azure Active Directory身份验证库（ADAL）迁移

适用于 Android 的Azure Active Directory身份验证库（ADAL）已于 2023 年 6 月弃用。 如果你或你的组织使用适用于 Android 的Azure Active Directory身份验证库（ADAL），则应迁移到 MSAL Android，以避免将应用的安全性置于危险之中。 适用于 Android 的 Microsoft 身份验证库 （MSAL）是可用于身份验证和令牌获取的受支持库。

MSAL Android 入门

若要在应用程序中使用 MSAL Android，需要：

由于 MSAL Android 同时支持浏览器委托身份验证和原生身份验证，请根据你的场景按照以下教程中的步骤操作。

要求

  • 最低 SDK 版本 16+
  • 目标 SDK 版本 33+

步骤 1：声明对 MSAL 的依赖项

将以下内容添加到应用的 build.gradle 文件中：

dependencies {
    implementation 'com.microsoft.identity.client:msal:4.9.+'
}

此外，请在 gradle 脚本中将以下行添加到存储库部分：

maven { 
    url 'https://pkgs.dev.azure.com/MicrosoftDeviceSDK/DuoSDK-Public/_packaging/Duo-SDK-Feed/maven/v1' 
}

步骤 2：创建 MSAL 配置文件

浏览器委托的身份验证：

在项目中将配置文件创建为“原始”资源。 在构造 PublicClientApplication 实例时使用生成的资源标识符来引用它。 如果你是首次在 Microsoft Entra 管理中心注册应用，还会获得详细的 MSAL Android 配置文件

{
  "client_id" : "<YOUR_CLIENT_ID>",
  "redirect_uri" : "msauth://<YOUR_PACKAGE_NAME>/<YOUR_BASE64_URL_ENCODED_PACKAGE_SIGNATURE>",
  "broker_redirect_uri_registered": true,
}

在 redirect_uri中， <YOUR_PACKAGE_NAME> 引用方法返回的 context.getPackageName() 包名称。 此包名称与 application_id 文件中定义的 build.gradle 名称相同。

上述值是所需的最低配置。 对于所有其他设置，MSAL 都使用该库附带的默认值。 请参阅 MSAL Android 配置文件文档 以了解库默认值。

本机身份验证：

  1. 右键单击 res 并选择“新建 > 目录”。 输入 raw 作为新目录名称，然后选择“确定”。
  2. 在此新文件夹中（应用 > src > main > res > raw），创建名为 auth_config_native_auth.json 的新 JSON 文件，并粘贴以下模板 MSAL 配置：
{ 
  "client_id": "Enter_the_Application_Id_Here", 
  "authorities": [ 
    { 
      "type": "CIAM", 
      "authority_url": "https://Enter_the_Tenant_Subdomain_Here.ciamlogin.com/Enter_the_Tenant_Subdomain_Here.onmicrosoft.com/" 
    } 
  ], 
  "challenge_types": ["oob"], 
  "logging": { 
    "pii_enabled": false, 
    "log_level": "INFO", 
    "logcat_enabled": true 
  } 
 }

步骤 3：为浏览器委托身份验证配置 AndroidManifest.xml

  1. 通过 Android Manifest 请求以下权限
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
  1. 在 Android Manifest 中配置意图筛选器，使用你的重定向 URI

未能包含与通过配置指定的重定向 URI 匹配的意向筛选器将导致交互式令牌请求失败。

    <!--Intent filter to capture authorization code response from the default browser on the device calling back to our app after interactive sign in -->
    <activity
        android:name="com.microsoft.identity.client.BrowserTabActivity">
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />
            <data
                android:scheme="msauth"
                android:host="<YOUR_PACKAGE_NAME>"
                android:path="/<YOUR_BASE64_ENCODED_PACKAGE_SIGNATURE>" />
        </intent-filter>
    </activity>

有关常见重定向 URI 问题的详细信息，请参阅 MSAL Android 常见问题解答 。

ProGuard

MSAL 在运行时使用存储在 .class 文件中的反射和泛型类型信息，以支持各种与持久化和序列化相关的功能。 库对最小化和混淆的支持有限。 此库附带了默认配置;如果发现任何问题，请 提交问题 。

Recommendation

MSAL 是一个安全库。 它控制用户登录和访问服务的方式。 建议在可以时始终在应用中使用最新版本的库。 我们使用 语义版本控制 ，以便你可以控制更新应用的风险。 例如，始终下载最新的次版本（例如 x.y.x）可确保您获得最新的安全更新和功能增强，同时还能确保我们的 API 表面未发生变化。 始终可以在GitHub的“发布”选项卡下看到最新版本和发行说明。

  • Last updated on