更新记录

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退出登录
• 错误处理
• 常见问题

功能支持矩阵

📚 推荐阅读

• Microsoft身份验证库(MSAL)文档
• Microsoft Graph API 文档

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法 ⚠️ 测试前需确保应用已在 Azure AD 完成注册和配置 ⚠️ iOS 平台需要配置 URL Scheme 用于回调 ⚠️ Android 平台返回授权码(code)，需要通过后端接口换取 access_token

环境配置

前置条件

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

iOS平台配置

配置插件Info.plist

直接修改插件根目录的 uni_modules/tt-microsoft-signin/utssdk/app-ios/Info.plist 文件：

<?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>
          <!-- URL Scheme 格式为 msauth.{Bundle Identifier} -->
          <string>msauth.com.yourcompany.yourapp</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

重要说明：

• CFBundleURLSchemes 中的值格式为 msauth.{Bundle Identifier}
• 确保与 Azure Portal 中配置的重定向 URI 一致
• iOS 平台使用 MSAL (Microsoft Authentication Library)，已在 config.json 中自动配置 Pod 依赖

Android平台配置

✅ 无需额外配置：Android 平台无需修改 AndroidManifest.xml 文件，插件已自动处理相关配置。

重要说明：

• Android 平台需要在 Azure Portal 中配置重定向 URI，格式为：{your-package-name}://auth
• 例如：com.example.app://auth
• Android 平台使用系统浏览器进行授权，返回授权码(code)，需要通过后端接口换取 access_token

快速开始

1. 导入插件

uni-app x 平台（推荐使用 Composition API）

import * as msdk from "@/uni_modules/tt-microsoft-signin";
import { ref, onMounted, onUnmounted } from 'vue';

export default {
    setup() {
        const microsoftImpl = ref<msdk.TTMicrosoftSDK | null>(null);

        onMounted(() => {
            // 获取Microsoft SDK实例
            microsoftImpl.value = msdk.getTTMicrosoftSDK();
        });

        onUnmounted(() => {
            microsoftImpl.value = null;
        });

        return {
            microsoftImpl
        };
    }
}

uni-app x 平台（Options API）

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

export default {
    data() {
        return {
            microsoftImpl: null as msdk.TTMicrosoftSDK | null,
        }
    },
    onLoad() {
        // 初始化Microsoft SDK实例
        this.microsoftImpl = msdk.getTTMicrosoftSDK();
    }
}

uni-app 平台

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

export default {
    data() {
        return {
            microsoftImpl: null
        }
    },
    onLoad() {
        // 初始化Microsoft SDK实例
        this.microsoftImpl = msdk.getTTMicrosoftSDK();
    }
}

功能介绍

• Microsoft授权登录
• Microsoft退出登录

Microsoft授权登录

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

⚠️ 平台差异：

• iOS平台：直接返回 accessToken（存储在 code 字段中）
• Android平台：返回授权码 code，需要通过后端接口换取 accessToken

参数说明

TTMicrosoftLoginOptions

返回值 TTMicrosoftLoginSuccess

常用权限范围 (Scopes)

示例代码

uni-app x 平台（Composition API - 推荐）

<script setup>
import * as msdk from "@/uni_modules/tt-microsoft-signin";
import { ref, onMounted, onUnmounted } from 'vue';

const microsoftImpl = ref<msdk.TTMicrosoftSDK | null>(null);
const userInfo = ref<msdk.TTMicrosoftLoginSuccess | null>(null);

onMounted(() => {
    // 获取Microsoft SDK实例
    microsoftImpl.value = msdk.getTTMicrosoftSDK();
});

onUnmounted(() => {
    microsoftImpl.value = null;
});

// 初始化Microsoft SDK
const register = () => {
    microsoftImpl.value?.register({
        clientId: '此处填写您的Microsoft Client ID',
        authority: 'https://login.microsoftonline.com/common', // 可选，默认值
        redirectUri: null, // 可选
        success: () => {
            console.log('Microsoft SDK初始化成功');
            uni.showToast({
                title: 'Microsoft SDK初始化成功',
                icon: 'success'
            });
        },
        fail: (err) => {
            console.error('Microsoft SDK初始化失败', err);
            uni.showToast({
                title: `初始化失败: ${err?.errMsg ?? ''}`,
                icon: 'error'
            });
        }
    } as msdk.TTMicrosoftRegisterOptions);
};

// Microsoft登录
const msLogin = () => {
    microsoftImpl.value?.login({
        permissions: ['User.Read', 'email'], // 可选，默认值
        success: (res) => {
            userInfo.value = res;
            console.log('Microsoft登录成功', res);
            console.log('Code:', res.code);
            console.log('用户ID:', res.userID);

            // iOS平台：res.code 是 accessToken，可直接使用
            // Android平台：res.code 是授权码，需要通过后端接口换取 accessToken
            // #ifdef APP-ANDROID
            exchangeCodeForToken(res.code);
            // #endif

            // #ifdef APP-IOS
            // iOS平台直接使用 accessToken
            sendTokenToServer(res.code);
            // #endif

            uni.showToast({
                title: 'Microsoft登录成功',
                icon: 'success'
            });
        },
        fail: (err) => {
            console.error('Microsoft登录失败', err);
            uni.showToast({
                title: `登录失败: ${err?.errMsg ?? ''}`,
                icon: 'error'
            });
        }
    } as msdk.TTMicrosoftLoginOptions);
};

// Android平台：通过授权码换取 access_token
const exchangeCodeForToken = (code: string) => {
    uni.request({
        url: 'https://your-server.com/api/microsoft/token',
        method: 'POST',
        data: {
            code: code,
            clientId: '您的Microsoft Client ID',
            redirectUri: '您的重定向URI'
        },
        success: (res) => {
            console.log('获取Token成功:', res.data);
            const accessToken = res.data.access_token;
            // 使用 accessToken 获取用户信息
            getUserInfo(accessToken);
        },
        fail: (err) => {
            console.error('获取Token失败:', err);
            uni.showToast({
                title: '获取Token失败',
                icon: 'error'
            });
        }
    });
};

// 使用 accessToken 获取用户信息
const getUserInfo = (accessToken: string) => {
    uni.request({
        url: 'https://graph.microsoft.com/v1.0/me',
        method: 'GET',
        header: {
            'Authorization': `Bearer ${accessToken}`
        },
        success: (res) => {
            console.log('用户信息:', res.data);
        },
        fail: (err) => {
            console.error('获取用户信息失败:', err);
        }
    });
};

// iOS平台：发送token到后端服务器
const 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);
        }
    });
};
</script>

uni-app x 平台（Options API）

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

export default {
    data() {
        return {
            microsoftImpl: null as msdk.TTMicrosoftSDK | null,
            userInfo: null as msdk.TTMicrosoftLoginSuccess | null
        }
    },
    onLoad() {
        // 获取Microsoft SDK实例
        this.microsoftImpl = msdk.getTTMicrosoftSDK();
    },
    methods: {
        // 初始化Microsoft SDK
        register() {
            this.microsoftImpl?.register({
                clientId: '此处填写您的Microsoft Client ID',
                authority: 'https://login.microsoftonline.com/common',
                redirectUri: null,
                success: () => {
                    console.log('Microsoft SDK初始化成功');
                    uni.showToast({
                        title: 'Microsoft SDK初始化成功',
                        icon: 'success'
                    });
                },
                fail: (err) => {
                    console.error('Microsoft SDK初始化失败', err);
                    uni.showToast({
                        title: `初始化失败: ${err?.errMsg ?? ''}`,
                        icon: 'error'
                    });
                }
            } as msdk.TTMicrosoftRegisterOptions);
        },

        // Microsoft登录
        msLogin() {
            this.microsoftImpl?.login({
                permissions: ['User.Read', 'email'],
                success: (res) => {
                    this.userInfo = res;
                    console.log('Microsoft登录成功', res);
                    console.log('Code:', res.code);
                    console.log('用户ID:', res.userID);

                    // #ifdef APP-ANDROID
                    // Android平台需要通过后端接口换取 accessToken
                    this.exchangeCodeForToken(res.code);
                    // #endif

                    // #ifdef APP-IOS
                    // iOS平台直接使用 accessToken
                    this.sendTokenToServer(res.code);
                    // #endif

                    uni.showToast({
                        title: 'Microsoft登录成功',
                        icon: 'success'
                    });
                },
                fail: (err) => {
                    console.error('Microsoft登录失败', err);
                    uni.showToast({
                        title: `登录失败: ${err?.errMsg ?? ''}`,
                        icon: 'error'
                    });
                }
            } as msdk.TTMicrosoftLoginOptions);
        },

        // Android平台：通过授权码换取 access_token
        exchangeCodeForToken(code: string) {
            uni.request({
                url: 'https://your-server.com/api/microsoft/token',
                method: 'POST',
                data: {
                    code: code,
                    clientId: '您的Microsoft Client ID',
                    redirectUri: '您的重定向URI'
                },
                success: (res) => {
                    console.log('获取Token成功:', res.data);
                    const accessToken = res.data.access_token;
                    this.getUserInfo(accessToken);
                },
                fail: (err) => {
                    console.error('获取Token失败:', err);
                }
            });
        },

        // 使用 accessToken 获取用户信息
        getUserInfo(accessToken: string) {
            uni.request({
                url: 'https://graph.microsoft.com/v1.0/me',
                method: 'GET',
                header: {
                    'Authorization': `Bearer ${accessToken}`
                },
                success: (res) => {
                    console.log('用户信息:', res.data);
                },
                fail: (err) => {
                    console.error('获取用户信息失败:', err);
                }
            });
        },

        // iOS平台：发送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 平台

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

export default {
    data() {
        return {
            microsoftImpl: null,
            userInfo: null
        }
    },
    onLoad() {
        // 初始化Microsoft SDK实例
        this.microsoftImpl = msdk.getTTMicrosoftSDK();
    },
    methods: {
        // 初始化Microsoft SDK
        register() {
            this.microsoftImpl.register({
                clientId: '此处填写您的Microsoft Client ID',
                authority: 'https://login.microsoftonline.com/common',
                redirectUri: null,
                success: () => {
                    console.log('Microsoft SDK初始化成功');
                    uni.showToast({
                        title: 'Microsoft SDK初始化成功',
                        icon: 'success'
                    });
                },
                fail: (err) => {
                    console.error('Microsoft SDK初始化失败', err);
                    uni.showToast({
                        title: `初始化失败: ${err?.errMsg ?? ''}`,
                        icon: 'error'
                    });
                }
            });
        },

        // Microsoft登录
        msLogin() {
            this.microsoftImpl.login({
                permissions: ['User.Read', 'email'],
                success: (res) => {
                    this.userInfo = res;
                    console.log('Microsoft登录成功', res);
                    console.log('Code:', res.code);
                    console.log('用户ID:', res.userID);

                    // #ifdef APP-ANDROID
                    // Android平台需要通过后端接口换取 accessToken
                    this.exchangeCodeForToken(res.code);
                    // #endif

                    // #ifdef APP-IOS
                    // iOS平台直接使用 accessToken
                    this.sendTokenToServer(res.code);
                    // #endif

                    uni.showToast({
                        title: 'Microsoft登录成功',
                        icon: 'success'
                    });
                },
                fail: (err) => {
                    console.error('Microsoft登录失败', err);
                    uni.showToast({
                        title: `登录失败: ${err?.errMsg ?? ''}`,
                        icon: 'error'
                    });
                }
            });
        },

        // Android平台：通过授权码换取 access_token
        exchangeCodeForToken(code) {
            uni.request({
                url: 'https://your-server.com/api/microsoft/token',
                method: 'POST',
                data: {
                    code: code,
                    clientId: '您的Microsoft Client ID',
                    redirectUri: '您的重定向URI'
                },
                success: (res) => {
                    console.log('获取Token成功:', res.data);
                    const accessToken = res.data.access_token;
                    this.getUserInfo(accessToken);
                },
                fail: (err) => {
                    console.error('获取Token失败:', err);
                }
            });
        },

        // 使用 accessToken 获取用户信息
        getUserInfo(accessToken) {
            uni.request({
                url: 'https://graph.microsoft.com/v1.0/me',
                method: 'GET',
                header: {
                    'Authorization': `Bearer ${accessToken}`
                },
                success: (res) => {
                    console.log('用户信息:', res.data);
                },
                fail: (err) => {
                    console.error('获取用户信息失败:', err);
                }
            });
        },

        // iOS平台：发送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 库进行身份验证
• 支持静默登录和交互式登录
• 可直接使用返回的 code 作为 accessToken

Android 平台

• 返回授权码 code，需要通过后端接口换取 accessToken
• 使用系统浏览器进行授权
• 需要配置回调 Activity（插件已自动配置）
• 必须通过后端接口将授权码换取 accessToken

后端接口示例（Android平台）

Android 平台需要使用授权码换取 access_token，后端接口示例：

// Node.js 示例
const axios = require('axios');

async function exchangeCodeForToken(code, clientId, clientSecret, redirectUri) {
    try {
        const response = await axios.post('https://login.microsoftonline.com/common/oauth2/v2.0/token', {
            client_id: clientId,
            client_secret: clientSecret,
            code: code,
            redirect_uri: redirectUri,
            grant_type: 'authorization_code'
        }, {
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded'
            }
        });

        return {
            access_token: response.data.access_token,
            refresh_token: response.data.refresh_token,
            expires_in: response.data.expires_in
        };
    } catch (error) {
        console.error('换取Token失败:', error);
        throw error;
    }
}

📖 详细文档：请参考Microsoft OAuth 2.0 授权码流程

Microsoft退出登录

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

参数说明

TTMicrosoftLogoutOptions

返回值 TTMicrosoftLogoutSuccess

空对象，表示退出成功

示例代码

uni-app x 平台（Composition API - 推荐）

// Microsoft退出登录
const msLogout = () => {
    microsoftImpl.value?.logout({
        success: () => {
            userInfo.value = null;
            console.log('Microsoft退出登录成功');
            uni.showToast({
                title: '退出登录成功',
                icon: 'success'
            });
        },
        fail: (err) => {
            console.error('Microsoft退出登录失败', err);
            uni.showToast({
                title: `退出登录失败: ${err?.errMsg ?? ''}`,
                icon: 'error'
            });
        }
    } as msdk.TTMicrosoftLogoutOptions);
};

uni-app x 平台（Options API）

// Microsoft退出登录
msLogout() {
    this.microsoftImpl?.logout({
        success: () => {
            this.userInfo = null;
            console.log('Microsoft退出登录成功');
            uni.showToast({
                title: '退出登录成功',
                icon: 'success'
            });
        },
        fail: (err) => {
            console.error('Microsoft退出登录失败', err);
            uni.showToast({
                title: `退出登录失败: ${err?.errMsg ?? ''}`,
                icon: 'error'
            });
        }
    } as msdk.TTMicrosoftLogoutOptions);
}

uni-app 平台

// Microsoft退出登录
msLogout() {
    this.microsoftImpl.logout({
        success: () => {
            this.userInfo = null;
            console.log('Microsoft退出登录成功');
            uni.showToast({
                title: '退出登录成功',
                icon: 'success'
            });
        },
        fail: (err) => {
            console.error('Microsoft退出登录失败', err);
            uni.showToast({
                title: `退出登录失败: ${err?.errMsg ?? ''}`,
                icon: 'error'
            });
        }
    });
}

错误处理

错误码说明

错误处理示例

uni-app x 平台（Composition API）

const msLogin = () => {
    microsoftImpl.value?.login({
        permissions: ['User.Read', 'email'],
        success: (result) => {
            console.log("✅ 登录成功:", result);
        },
        fail: (error) => {
            // 根据错误码进行不同处理
            switch(error.errCode) {
                case 101:
                    uni.showToast({
                        title: 'SDK未初始化，请先初始化',
                        icon: 'error'
                    });
                    break;
                case 102:
                    uni.showToast({
                        title: '授权回调参数错误',
                        icon: 'error'
                    });
                    break;
                case 103:
                    uni.showToast({
                        title: 'State校验失败，请重新登录',
                        icon: 'error'
                    });
                    break;
                case 104:
                    uni.showToast({
                        title: '打开授权页面失败',
                        icon: 'error'
                    });
                    break;
                default:
                    uni.showToast({
                        title: '登录失败: ' + error.errMsg,
                        icon: 'error'
                    });
            }
            console.error('登录失败:', error);
        }
    } as msdk.TTMicrosoftLoginOptions);
};

uni-app x 平台（Options API）

msLogin() {
    this.microsoftImpl?.login({
        permissions: ['User.Read', 'email'],
        success: (result) => {
            console.log("✅ 登录成功:", result);
        },
        fail: (error) => {
            // 根据错误码进行不同处理
            switch(error.errCode) {
                case 101:
                    uni.showToast({
                        title: 'SDK未初始化，请先初始化',
                        icon: 'error'
                    });
                    break;
                case 102:
                    uni.showToast({
                        title: '授权回调参数错误',
                        icon: 'error'
                    });
                    break;
                case 103:
                    uni.showToast({
                        title: 'State校验失败，请重新登录',
                        icon: 'error'
                    });
                    break;
                case 104:
                    uni.showToast({
                        title: '打开授权页面失败',
                        icon: 'error'
                    });
                    break;
                default:
                    uni.showToast({
                        title: '登录失败: ' + error.errMsg,
                        icon: 'error'
                    });
            }
            console.error('登录失败:', error);
        }
    } as msdk.TTMicrosoftLoginOptions);
}

uni-app 平台

msLogin() {
    this.microsoftImpl.login({
        permissions: ['User.Read', 'email'],
        success: (result) => {
            console.log("✅ 登录成功:", result);
        },
        fail: (error) => {
            // 根据错误码进行不同处理
            switch(error.errCode) {
                case 101:
                    uni.showToast({
                        title: 'SDK未初始化，请先初始化',
                        icon: 'error'
                    });
                    break;
                case 102:
                    uni.showToast({
                        title: '授权回调参数错误',
                        icon: 'error'
                    });
                    break;
                case 103:
                    uni.showToast({
                        title: 'State校验失败，请重新登录',
                        icon: 'error'
                    });
                    break;
                case 104:
                    uni.showToast({
                        title: '打开授权页面失败',
                        icon: 'error'
                    });
                    break;
                default:
                    uni.showToast({
                        title: '登录失败: ' + error.errMsg,
                        icon: 'error'
                    });
            }
            console.error('登录失败:', 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 配置是否正确（默认为 https://login.microsoftonline.com/common）
• 验证网络连接是否正常
• 查看详细错误信息（通过 error.errMsg 获取）

5. 登录失败？

解决方案:

• 检查权限范围（scopes）是否正确
• 确认应用已在 Azure Portal 配置相应权限
• 查看错误详情（通过 error.errMsg 获取错误信息）
• 验证用户是否已授权应用访问
• Android平台：确保后端接口能正确换取 accessToken

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

解决方案:

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

7. Android平台如何获取用户信息？

解决方案:

• Android 平台返回的是授权码(code)，需要通过后端接口换取 accessToken
• 使用 accessToken 调用 Microsoft Graph API 获取用户信息
• 参考：Microsoft Graph API 文档
• 示例代码见上方"后端接口示例"部分

8. State校验失败？

解决方案:

• State 用于防止 CSRF 攻击，由 SDK 自动生成和校验
• 如果校验失败，可能是授权流程被中断或重复调用
• 重新发起登录流程即可

9. Android平台授权码换取Token失败？

解决方案:

• 检查后端接口是否正确实现 OAuth 2.0 授权码流程
• 确认 clientId、clientSecret、redirectUri 是否正确
• 验证授权码是否过期（授权码有时效性）
• 参考：Microsoft OAuth 2.0 授权码流程

📞 技术支持

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

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

祝您开发愉快！ 🎉