Flutter Azure AD 登录插件dart_azure_ad_sign_in的使用

Flutter Azure AD 登录插件 dart_azure_ad_sign_in 的使用

1. 平台支持

2. 功能

dart_azure_ad_sign_in 插件允许 Flutter 和 Dart 应用程序获取用于访问受保护资源（如 Azure Web API）的认证令牌。该插件可以无需任何配置即可使用，提供与 Azure CLI 相同的访问权限，也可以通过配置来修改访问权限。

3. 认证流程

4. 入门指南

4.1 安装

前往 Pub.dev 获取最新版本。

4.2 导入

在 Dart 文件中导入 dart_azure_ad_sign_in 包：

import 'package:dart_azure_ad_sign_in/dart_azure_ad_sign_in.dart';

4.3 Android 设置

4.3.1 网络设置

确保在 AndroidManifest.xml 中启用网络权限：

<manifest xmlns:android...>
  ...
  <uses-permission android:name="android.permission.INTERNET" />
  <application ...
</manifest>

4.3.2 明文流量

创建 res/xml/network_security_config.xml 文件并配置如下：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
    </domain-config>
</network-security-config>

然后在 AndroidManifest.xml 中加载该文件：

<?xml version="1.0" encoding="utf-8"?>
<manifest ...>
    <application
        ...
        android:networkSecurityConfig="@xml/network_security_config"
        ...>
        ...
    </application>
</manifest>

4.4 iOS 设置

4.4.1 网络设置

iOS 不需要额外的网络设置。

4.4.2 明文流量

在 info.plist 中添加以下规则以允许本地主机的明文流量：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <false/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>localhost</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSTemporaryExceptionMinimumTLSVersion</key>
            <string>TLSv1.1</string>
        </dict>
    </dict>
</dict>

4.5 macOS 设置

4.5.1 网络设置

在 .entitlements 文件中启用网络权限：

<key>com.apple.security.network.client</key>
<true/>

4.5.2 明文流量

在 info.plist 中添加以下规则以允许本地主机的明文流量：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <false/>
    <key>NSExceptionDomains</key>
    <dict>
        <key>localhost</key>
        <dict>
            <key>NSIncludesSubdomains</key>
            <true/>
            <key>NSTemporaryExceptionAllowsInsecureHTTPLoads</key>
            <true/>
            <key>NSTemporaryExceptionMinimumTLSVersion</key>
            <string>TLSv1.1</string>
        </dict>
    </dict>
</dict>

4.6 Windows 设置

无需额外设置。

4.7 Linux 设置

无需额外设置。

5. 使用方法

5.1 创建和配置 AzureSignIn 实例

AzureSignIn 类非常灵活，无需设置参数即可使用，默认会使用 Azure CLI 配置。有关所有可用变量的详细信息，请参阅 AzureSignIn 变量。

5.1.1 使用默认设置创建实例

final azureSignIn = AzureSignIn();

5.1.2 使用参数创建实例

如果需要，可以设置认证和本地 HTTP 服务器的参数：

final azureSignIn = AzureSignIn(
  // 应用程序（客户端）ID，Azure 门户 - 应用注册页面分配给你的应用。
  clientId: '04b07795-8ddb-461a-bbee-02f9e1bf7b46',
  // 用户需要同意的权限范围。
  scope: [
    'https://management.core.windows.net//.default',
    'offline_access',
    'openid',
    'profile',
  ],
  // 本地 HTTP 服务器的端口，用于接收登录后的代码。
  port: 5000,
  // 登录成功后用户在浏览器中看到的响应。
  serverSuccessResponse: '<h1>登录成功。</h1><p>可以关闭此窗口。</p>',
  // 登录失败后用户在浏览器中看到的响应。
  serverErrorResponse: '<h1>登录失败。</h1><p>请关闭此窗口并重试。</p>',
  // 本地 HTTP 服务器等待用户登录的时间。
  signInTimeoutDuration: Duration(minutes: 5),
);

5.2 登录

5.2.1 获取 Microsoft 登录页面 URL

用户需要在浏览器中登录，可以通过 signInUri 获取登录 URL。如果使用 Flutter，可以使用 url_launcher 插件打开该 URL。

// 打印登录 URL，用户需要在浏览器中打开。
print(azureSignIn.signInUri);

5.2.2 启动登录过程

启动登录过程将返回一个新的 Token。在后台，会启动一个 HttpServer，等待浏览器登录后接收到代码，然后调用 Microsoft Token Endpoint 获取令牌。

Token token = await azureSignIn.signIn();

5.3 取消登录过程

用户可以在需要时取消登录过程。azureSignIn.signIn() 将返回一个带有取消信息的 Token。

// 取消登录过程。
await azureSignIn.cancelSignIn();

5.4 刷新令牌

当令牌过期时，可以通过提供现有的 Token 或刷新令牌字符串来刷新令牌。

5.4.1 使用现有 Token 刷新

// 使用现有令牌对象刷新令牌。
token = await azureSignIn.refreshToken(token: token);

5.4.2 使用刷新令牌字符串刷新

// 使用刷新令牌字符串刷新令牌。
token = await azureSignIn.refreshToken(refreshToken: refreshTokenString);

5.5 AzureSignIn 变量

5.6 Token 实体

6. 下一步

使用 token.accessToken，你现在已经可以访问 Microsoft APIs。更多关于 Azure REST API 的信息可以参考 Azure Rest API 参考，或查看 常用 Microsoft 应用程序的应用 ID 以添加一些预定义的 azureSignIn.clientId。

7. Bug 和问题

请在 GitHub Issues 提交功能请求和 bug。

完整示例 Demo

以下是一个完整的示例，展示了如何使用 dart_azure_ad_sign_in 插件进行 Azure AD 登录和令牌刷新：

// Copyright 2023 Patrick Hettich. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

import 'package:dart_azure_ad_sign_in/dart_azure_ad_sign_in.dart';

void main(List<String> args) async {
  // 创建 Azure SignIn 实例，所有参数都是可选的。
  final azureSignIn = AzureSignIn();

  // 打印登录 URL。
  print(azureSignIn.signInUri);

  // 启动 HTTP 服务器并等待用户登录。
  // 也可以通过 azureSignIn.cancelSignIn() 取消登录。
  Token token = await azureSignIn.signIn();

  // 打印令牌信息
  printToken(token: token, title: '初始令牌');

  // 刷新过期的令牌
  token = await azureSignIn.refreshToken(token: token);

  // 打印更新后的令牌信息
  printToken(token: token, title: '刷新后的令牌');
}

void printToken({required Token token, required String title}) {
  print(
      '------------------------------------------------------------------------------------------------------------------------------------');
  print(title);
  print(
      '------------------------------------------------------------------------------------------------------------------------------------');
  print('状态: ${token.status}');
  print('错误: ${token.error}');
  print('错误消息: ${token.errorDescription}');
  print('访问令牌:');
  print(token.accessToken);
  print('刷新令牌:');
  print(token.refreshToken);
}