Office Add-in身份认证迁移咨询：替换Office-JS-helpers实现Azure AD SSO

前置准备 #

• 确认项目中office-js包版本≥1.9.0（推荐使用最新稳定版），原生SSO API需要此版本支持
• 拥有Azure AD管理员权限，用于配置应用注册
• 确保Azure Service Fabric后端已启用Azure AD身份认证保护

步骤1：移除Office-JS-helpers依赖与旧认证逻辑 #

• 卸载依赖：npm uninstall office-js-helpers
• 删除项目中所有基于AuthenticationContext的认证代码，包括弹窗登录、手动令牌获取逻辑
• 清理旧的认证相关配置（如adalConfig等）

步骤2：集成Office.js原生SSO API #

在React组件中实现SSO令牌获取逻辑：

// 初始化Office（建议在App组件加载时执行）
async function initOffice() {
  await Office.onReady();
  if (Office.context.auth) {
    console.log("SSO API已就绪");
  }
}

// 获取SSO访问令牌
async function getSSOToken() {
  try {
    const token = await Office.auth.getAccessToken({
      allowSignInPrompt: true,
      allowConsentPrompt: true,
      forMSGraphAccess: false // 如果需要直接调用Graph，设为true
    });
    return token;
  } catch (error) {
    switch (error.code) {
      case 13001: // 用户未登录Office
        // 引导用户登录Office客户端
        break;
      case 13002: // 需要用户授权
        // 提示用户授权权限
        break;
      case 13003: // 令牌获取失败
        // 处理通用错误
        break;
      default:
        // 其他错误处理
    }
    throw error;
  }
}

• 将令牌缓存至内存或本地存储，避免重复调用API
• 实现令牌过期自动刷新逻辑：通过解析令牌的exp字段判断有效期，提前调用getAccessToken刷新

步骤3：配置Azure AD应用注册 #

• 复用现有Azure AD应用或新建应用注册：
  1. 进入Azure门户→Azure AD→应用注册→选择目标应用
  2. 配置单一登录：设置重定向URI为插件的部署域名（如https://<your-sf-domain>/auth-callback），平台选择"Office Add-in"
  3. 添加API权限：
     • 针对Outlook：添加Office 365 Exchange Online的委托权限（如Mail.Read）
     • 针对Word：添加Microsoft Graph的委托权限（如Files.ReadWrite）
     • 添加后端Service Fabric服务的API权限（若后端受Azure AD保护）
  4. 设置应用程序ID URI，确保与插件中配置的clientId对应

步骤4：适配Azure Service Fabric后端 #

• 确保后端服务的Azure AD认证配置接受SSO令牌：
  1. 验证令牌的签名、受众(aud)、颁发者(iss)合法性
  2. 若后端需要调用Microsoft Graph，可通过SSO令牌获取委托权限的Graph访问令牌（使用OAuth2.0的on-behalf-of流程）
• 调整后端API的权限验证逻辑，兼容SSO令牌的格式与权限声明

步骤5：针对Word/Outlook的特殊适配 #

• Word插件：在Office.onReady()确认文档加载完成后再调用SSO逻辑，避免初始化时机冲突
• Outlook插件：
  • 在阅读邮件场景下，可在插件加载时直接触发SSO
  • 在撰写邮件场景下，需确保用户交互后再调用SSO（避免客户端拦截）
  • 注意桌面端与Web端的SSO行为差异，测试不同环境下的授权流程

步骤6：测试与调试 #

• 本地测试：配置Azure AD应用注册的重定向URI允许本地地址（如https://localhost:3000/auth-callback），使用Office Web客户端或桌面客户端调试
• 部署测试：将插件部署至Azure Service Fabric后，验证域名与Azure AD配置一致，测试静默登录、令牌刷新、权限授权流程
• 错误场景测试：模拟用户未登录、拒绝授权、令牌过期等情况，确保错误处理逻辑生效

内容的提问来源于stack exchange，提问作者Dhiluraj