更新记录

1.0.1（2025-11-22）

已知问题修复

1.0.0（2025-11-22）

支持 安卓 iOS平台 微软授权登录功能

平台兼容性

uni-app(4.76)

uni-app x(4.76)

tt-microsoft-signin

🚀 Microsoft 登录SDK插件，为 uni-app x & uni-app 提供 Microsoft 账号登录功能

📱 支持平台：uni-app x (TypeScript) 和 uni-app (JavaScript)

📖 目录

• SDK版本信息
• 环境配置
• 快速开始
• 基础使用
• 功能介绍
  • Microsoft授权登录
  • Microsoft退出登录
• 错误处理
• 常见问题

SDK版本信息

📚 推荐阅读: Microsoft身份验证库(MSAL)文档

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法 ⚠️ 测试前需确保应用已在 Azure AD 完成注册和配置 ⚠️ iOS 平台需要配置 URL Scheme 用于回调

环境配置

前置条件

1. 在Azure Portal注册应用
2. 获取 Client ID (应用程序ID)
3. 配置重定向 URI (Redirect URI)
4. 配置应用权限 (API Permissions)

iOS平台配置

1. 配置 URL Scheme

在项目根目录的 Info.plist 或插件内的 uni_modules/tt-microsoft-signin/utssdk/app-ios/Info.plist 中添加 URL Scheme 配置：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
          <string>msauth.com.yourcompany.yourapp</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

💡 配置说明:

• CFBundleURLSchemes 中的值格式为 msauth.{Bundle Identifier}
• 确保与 Azure Portal 中配置的重定向 URI 一致

2. 依赖配置

iOS 平台使用 MSAL (Microsoft Authentication Library)，已在 config.json 中自动配置 Pod 依赖。

Android平台配置

1. 配置重定向 URI

Android 平台需要在 Azure Portal 中配置重定向 URI，格式为：

{your-package-name}://auth

例如：com.example.app://auth

2. AndroidManifest.xml

插件已自动配置必要的 Activity 和权限，无需手动修改。

快速开始

1. 导入插件

uni-app x 版本

import * as msdk from "@/uni_modules/tt-microsoft-signin";

export default {
    data() {
        return {
            microsoft: null as msdk.TTMicrosoftSDK | null,
        }
    },
    onLoad() {
        // 初始化Microsoft SDK实例
        this.microsoft = msdk.getTTMicrosoftSDK()
        // 注册Microsoft SDK
        this.initMicrosoftSDK()
    },
    methods: {
        // 初始化Microsoft SDK
        initMicrosoftSDK() {
            // SDK初始化代码见下方
        }
    }
}

uni-app 版本

// 在页面中引入插件
import * as msdk from "@/uni_modules/tt-microsoft-signin";

export default {
    data() {
        return {
            microsoft: null
        }
    },
    onLoad() {
        // 初始化Microsoft SDK实例
        this.microsoft = msdk.getTTMicrosoftSDK()
        // 注册Microsoft SDK
        this.initMicrosoftSDK()
    },
    methods: {
        // 初始化Microsoft SDK
        initMicrosoftSDK() {
            // SDK初始化代码见下方
        }
    }
}

2. 初始化 SDK

uni-app x 版本

initMicrosoftSDK() {
    if (this.microsoft == null) {
        console.error('Microsoft SDK初始化失败')
        return
    }

    this.microsoft?.register({
        clientId: "您的Microsoft Client ID",           // 必填：Azure Portal中获取的应用程序ID
        authority: "https://login.microsoftonline.com/common", // 可选：AAD Authority，默认为common
        redirectUri: null,                             // 可选：重定向URI，iOS会自动使用URL Scheme
        success: (e) => {
            console.log("✅ Microsoft SDK初始化成功");
            // SDK初始化完成，可以进行后续操作
        },
        fail: (err) => {
            console.error("❌ Microsoft SDK初始化失败:", err);
            uni.showToast({
                title: 'Microsoft SDK初始化失败',
                icon: 'error'
            })
        }
    } as msdk.TTMicrosoftRegisterOptions);
}

uni-app 版本

initMicrosoftSDK() {
    if (this.microsoft == null) {
        console.error('Microsoft SDK初始化失败')
        return
    }

    this.microsoft.register({
        clientId: "您的Microsoft Client ID",           // 必填：Azure Portal中获取的应用程序ID
        authority: "https://login.microsoftonline.com/common", // 可选：AAD Authority，默认为common
        redirectUri: null,                             // 可选：重定向URI
        success: (e) => {
            console.log("✅ Microsoft SDK初始化成功");
            // SDK初始化完成，可以进行后续操作
        },
        fail: (err) => {
            console.error("❌ Microsoft SDK初始化失败:", err);
            uni.showToast({
                title: 'Microsoft SDK初始化失败',
                icon: 'error'
            })
        }
    });
}

基础使用

💡 Microsoft 登录支持多种权限范围，可根据需求配置不同的 scopes

功能介绍

Microsoft授权登录

💡 Microsoft 登录使用 OAuth 2.0 协议，支持获取访问令牌和用户信息

参数说明

TTMicrosoftLoginOptions

返回值 TTMicrosoftLoginSuccess

常用权限范围 (Scopes)

示例代码

uni-app x 版本

// Microsoft授权登录
handleMicrosoftLogin() {
    this.microsoft?.login({
        permissions: ['User.Read', 'email'], // 可选，默认值
        success: (result) => {
            console.log("✅ Microsoft登录成功");
            console.log("Access Token:", result.code);
            console.log("用户ID:", result.userID);
            console.log("用户名称:", result.name);
            console.log("用户邮箱:", result.email);
            console.log("用户头像:", result.pictureURL);

            // 保存用户信息
            this.userInfo = result;

            // 如果需要，可以将token发送到后端服务器
            this.sendTokenToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ Microsoft登录失败:", error);
            uni.showToast({
                title: '登录失败: ' + (error.errMsg || '未知错误'),
                icon: 'error'
            })
        }
    } as msdk.TTMicrosoftLoginOptions)
}

// 发送token到后端服务器
sendTokenToServer(token: string) {
    uni.request({
        url: 'https://your-server.com/api/microsoft/verify',
        method: 'POST',
        data: { token },
        success: (res) => {
            // 处理验证成功逻辑
            console.log('Token验证成功:', res.data)
        },
        fail: (err) => {
            console.error('Token验证失败:', err)
        }
    })
}

uni-app 版本

// Microsoft授权登录
handleMicrosoftLogin() {
    this.microsoft.login({
        permissions: ['User.Read', 'email'], // 可选，默认值
        success: (result) => {
            console.log("✅ Microsoft登录成功");
            console.log("Access Token:", result.code);
            console.log("用户ID:", result.userID);
            console.log("用户名称:", result.name);
            console.log("用户邮箱:", result.email);
            console.log("用户头像:", result.pictureURL);

            // 保存用户信息
            this.userInfo = result;

            // 如果需要，可以将token发送到后端服务器
            this.sendTokenToServer(result.code)
        },
        fail: (error) => {
            console.error("❌ Microsoft登录失败:", error);
            uni.showToast({
                title: '登录失败: ' + (error.errMsg || '未知错误'),
                icon: 'error'
            })
        }
    })
}

// 发送token到后端服务器
sendTokenToServer(token) {
    uni.request({
        url: 'https://your-server.com/api/microsoft/verify',
        method: 'POST',
        data: { token },
        success: (res) => {
            // 处理验证成功逻辑
            console.log('Token验证成功:', res.data)
        },
        fail: (err) => {
            console.error('Token验证失败:', err)
        }
    })
}

平台差异说明

iOS 平台

• 直接返回 accessToken（存储在 code 字段中）
• 使用 MSAL 库进行身份验证
• 支持静默登录和交互式登录

Android 平台

• 返回授权码 code，需要通过后端接口换取 accessToken
• 使用系统浏览器进行授权
• 需要配置回调 Activity

Microsoft退出登录

💡 清除本地缓存的 Microsoft 账号信息

参数说明

TTMicrosoftLogoutOptions

返回值 TTMicrosoftLogoutSuccess

示例代码

uni-app x 版本

// Microsoft退出登录
handleMicrosoftLogout() {
    this.microsoft?.logout({
        success: () => {
            console.log("✅ Microsoft退出登录成功");
            // 清除本地用户信息
            this.userInfo = null;
            uni.showToast({
                title: '退出登录成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Microsoft退出登录失败:", error);
            uni.showToast({
                title: '退出登录失败: ' + (error.errMsg || '未知错误'),
                icon: 'error'
            })
        }
    } as msdk.TTMicrosoftLogoutOptions)
}

uni-app 版本

// Microsoft退出登录
handleMicrosoftLogout() {
    this.microsoft.logout({
        success: () => {
            console.log("✅ Microsoft退出登录成功");
            // 清除本地用户信息
            this.userInfo = null;
            uni.showToast({
                title: '退出登录成功',
                icon: 'success'
            })
        },
        fail: (error) => {
            console.error("❌ Microsoft退出登录失败:", error);
            uni.showToast({
                title: '退出登录失败: ' + (error.errMsg || '未知错误'),
                icon: 'error'
            })
        }
    })
}

错误处理

错误码说明

错误处理示例

uni-app x 版本

handleMicrosoftLogin() {
    this.microsoft?.login({
        permissions: ['User.Read', 'email'],
        success: (result) => {
            console.log("✅ 登录成功:", result);
        },
        fail: (error) => {
            // 根据错误码进行不同处理
            switch(error.errCode) {
                case 101:
                    uni.showToast({
                        title: 'SDK未初始化，请先初始化',
                        icon: 'error'
                    })
                    break
                default:
                    // 查看详细错误信息
                    if (error.cause) {
                        console.error('原始错误:', error.cause)
                        console.error('错误码:', error.cause.code)
                        console.error('错误信息:', error.cause.message)
                    }
                    uni.showToast({
                        title: '登录失败: ' + error.errMsg,
                        icon: 'error'
                    })
            }
        }
    } as msdk.TTMicrosoftLoginOptions)
}

uni-app 版本

handleMicrosoftLogin() {
    this.microsoft.login({
        permissions: ['User.Read', 'email'],
        success: (result) => {
            console.log("✅ 登录成功:", result);
        },
        fail: (error) => {
            // 根据错误码进行不同处理
            switch(error.errCode) {
                case 101:
                    uni.showToast({
                        title: 'SDK未初始化，请先初始化',
                        icon: 'error'
                    })
                    break
                default:
                    // 查看详细错误信息
                    if (error.cause) {
                        console.error('原始错误:', error.cause)
                        console.error('错误码:', error.cause.code)
                        console.error('错误信息:', error.cause.message)
                    }
                    uni.showToast({
                        title: '登录失败: ' + error.errMsg,
                        icon: 'error'
                    })
            }
        }
    })
}

常见问题

1. 找不到插件方法？

解决方案: 确保使用自定义基座运行，标准基座不包含原生插件。

2. iOS平台登录无响应？

解决方案:

• 检查 Info.plist 中的 URL Scheme 配置
• 确认 URL Scheme 格式为 msauth.{Bundle Identifier}
• 验证 Azure Portal 中的重定向 URI 配置
• 确保应用已在 Azure Portal 完成注册

3. Android平台授权后无法回调？

解决方案:

• 确认重定向 URI 格式为 {package-name}://auth
• 检查 AndroidManifest.xml 中的 Activity 配置
• 验证 Azure Portal 中的重定向 URI 配置
• 确保应用签名与配置一致

4. SDK初始化失败？

解决方案:

• 确认 Client ID 是否正确
• 检查 authority 配置是否正确
• 验证网络连接是否正常
• 查看详细错误信息（通过 error.cause 获取）

5. 登录失败？

解决方案:

• 检查权限范围（scopes）是否正确
• 确认应用已在 Azure Portal 配置相应权限
• 查看错误详情（通过 error.cause 获取原始错误信息）
• 验证用户是否已授权应用访问

6. iOS平台URL Scheme配置问题？

解决方案:

• URL Scheme 必须格式为 msauth.{Bundle Identifier}
• 确保与 Azure Portal 中配置的重定向 URI 一致
• 检查 Info.plist 文件格式是否正确
• 重新编译应用使配置生效

7. Android平台回调Activity问题？

解决方案:

• 插件已自动配置回调 Activity，无需手动修改
• 确保重定向 URI 与 AndroidManifest.xml 中的配置一致
• 检查应用包名是否正确

8. 如何获取用户详细信息？

解决方案:

• iOS 平台：登录成功后可直接从返回结果中获取用户信息
• Android 平台：需要使用返回的 code 通过后端接口换取 accessToken，然后调用 Microsoft Graph API 获取用户信息
• 参考：Microsoft Graph API 文档

📞 技术支持

如果在使用过程中遇到问题，请：

1. 查阅上方常见问题
2. 参考 Microsoft 官方开发文档
3. 检查配置是否正确
4. 确认 Azure Portal 应用配置

祝您开发愉快！ 🎉