Flutter使用aad_auth对接Dynamic CRM API时Azure AD认证失败解决方法

问题背景 #

• 业务目标：Flutter 应用对接 Dynamic CRM API，选用 aad_auth 包实现 Azure Active Directory (AAD) 身份认证流程
• 前置操作：已在 AAD 控制台完成应用注册，按官方文档指引完成了标注要求的配置项
• 故障表现：登录流程始终触发认证错误，无法完成正常鉴权
• 对应配置与报错截图：
  • AAD 应用配置：
  • Flutter 端配置：
  • 登录操作与报错信息：

逐点排查与修复方案 #

按优先级从高到低核对以下配置项，90%以上的同类问题都由配置不匹配导致：

• 重定向URI一致性校验
  • 必须保证 AAD 控制台「身份验证」页配置的重定向URI，和 Flutter 端初始化 aad_auth 时传入的 redirectUri 参数完全一致，包括大小写、路径、末尾是否带斜杠，不能有任何字符差异
  • 移动端场景属于公共客户端，必须在AAD身份验证页开启「允许公共客户端流」开关，该开关未开启时所有移动端鉴权请求会被直接拦截
• 权限与Scope参数校验
  • 对接Dynamic CRM不要误加Microsoft Graph相关权限，必须添加Dynamics CRM服务下的user_impersonation委托权限，添加完成后必须点击「授予管理员同意」按钮，否则租户下普通用户登录时会直接报权限不足错误
  • Flutter端传入的资源/Scope参数必须和你的CRM实例地址完全匹配，标准格式为https://<你的CRM实例名>.crm.dynamics.com/user_impersonation，不要错填成AAD全局资源地址
• Android端专属配置校验
  • AAD应用配置中填写的Android包名必须和Flutter项目build.gradle中配置的applicationId完全一致
  • 必须同时填写debug、release签名对应的SHA1哈希值，哈希值不匹配是Android端鉴权失败的高频原因，获取debug签名哈希可直接执行命令：

    keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore -list -v
    

    默认debug密钥库密码为android
• 基础参数一致性校验
  • 核对Flutter端传入的clientId必须和AAD应用概览页的「应用程序(客户端)ID」完全一致，单租户场景下tenantId不要错填为通用的common标识，必须填写对应租户的实际ID
  • 公共客户端场景（移动端）不要额外传入clientSecret参数，该参数仅适用于Web/后端等机密客户端场景，误传会直接触发鉴权错误
• 错误详情定位
  上述配置全部核对无误仍报错的，直接在代码中打印鉴权接口返回的完整错误体，根据AAD返回的错误码直接定位根因：

  AADSTS50011：重定向URI不匹配
  AADSTS65001：权限未授予管理员同意/Scope参数配置错误
  AADSTS70002：客户端参数校验失败，多为clientId错误或误传clientSecret导致
  AADSTS90002：租户ID填写错误

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