使用 Fleet 部署 Microsoft Entra ID Platform SSOmacOS 平台单点登录完整实战指南【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleetPlatform Single Sign-OnPlatform SSO是 Apple 在 WWDC22 上随 macOS Ventura、iOS 17 和 iPadOS 17 一起推出的身份验证能力它允许用户仅向身份提供商IdP凭据登录一次即可自动访问所有需要 IdP 认证的应用与网站。本指南以 deploying-entra-platform-sso-with-fleet.md 为骨架详细介绍如何将 Microsoft Entra ID 的 macOS Platform SSO 扩展部署到 Fleet 管理的 macOS 主机上——从上传 Company Portal 应用到构建com.apple.extensiblesso配置描述文件、再到部署与终端用户体验同时结合 Fleet 开源仓库中的示例配置entra-sso-extension-example.mobileconfig和 PSSO 设计文档docs/Contributing/mdm/apple/psso.md做源码级纵深讲解。读完本文你将掌握在 Fleet 中端到端部署 Entra ID Platform SSO 的完整流程以及 Secure Enclave 密钥认证与密码同步两种模式的核心差异。注Fleet 正在与 Entra ID 测试 Simplified Setup 能力在自动化设备注册ADE过程中激活并强制 Platform SSO用于认证注册、使用托管 Apple 账户登录并创建本地用户目前该能力处于 preview 状态。为什么要使用 Platform SSO如果你的身份提供商IdP支持 Platform Single Sign-On在企业环境中部署它可以为用户带来更优秀且更安全的登录体验免去重复输入凭据用户无需在每次登录 Entra ID 保护的应用时都输入凭据Platform SSO 扩展会自动使用基于 Secure Enclave 的密钥完成认证。加速认证流程整个认证过程对员工透明大幅减少等待与重复输入成本。更强的防钓鱼能力相比传统的用户名 密码认证Secure Enclave 密钥认证天然抵抗凭据钓鱼攻击——因为根本没有密码会在浏览器中被反复输入和截获。从 Fleet 仓库的设计文档看Fleet 实现 PSSO 的目标是让 macOS 本地账户密码与用户在上游 IdP 使用的凭据保持同步本地账户密码同步并支持在 Setup Assistant 期间使用与 IdP 同步的密码创建用户。Fleet 自身实现了 PSSO 扩展in-tree Swift extension将 Fleet 服务器作为 IdP-translator只要 IdP 支持 LDAP 或 OAuth ROPG就能满足这一需求详见 docs/Contributing/mdm/apple/psso.md。部署前置要求在开始之前请确认满足以下条件macOS 13 或更高版本Platform SSO 依赖 macOS Ventura 引入的 AppSSO 框架Microsoft Entra ID作为身份提供商一个开启了 Apple MDM 的 Fleet 服务器需要能推送配置描述文件与策略Microsoft 的 Company Portal 应用版本 5.2404.0 或更高iMazing Profile Editor可选用于构建配置描述文件如果使用Google Chrome需要安装 Microsoft 的单点登录扩展Microsoft Single Sign On ExtensionFleet 侧与 Platform SSO 相关的服务端能力注册端点、nonce 端点、token 端点、JWKS 端点以及设备注册密钥的存储在仓库源码中均有实现例如 server/fleet/apple_psso.go 定义了PSSODevice、PSSOKey、PSSOClaims、PSSOIdPClient等核心类型server/mdm/apple/psso 下则包含 JWE/JWT 加密pssocrypto包与注册令牌签发regtoken包的实现。第一步在 Fleet 中部署 Company Portal 应用上传 Company Portal 应用到 Fleet 服务器在你的 Fleet 服务器上选择要部署 Platform SSO 的 fleet团队。导航到Software Add software Custom package Choose file。选择你电脑上的CompanyPortal-Installer.pkg文件然后点击Add software按钮。上传后你需要决定 Company Portal 的安装方式Automatic自动Fleet 会自动创建一条策略来检测哪些主机没有安装 Company Portal 应用并为其自动安装。Manual手动你需要从单个主机的详情页Software标签页手动触发安装。仓库的 软件部署文档 中对自定义包custom package的分发机制有更详细的说明Fleet 通过 MDM 将自定义软件包推送给目标主机并可以配合策略policies实现检测-安装的闭环自动化。第二步构建 Platform SSO 配置描述文件主机安装好 Company Portal 应用后还需要部署一个配置描述文件来启用 Microsoft Enterprise SSO 插件。这是整个部署中最关键的一步。使用 iMazing Profile Editor 创建描述文件在你的 Mac 上打开iMazing Profile Editor。在General域中于Payload Display Name字段为 Platform SSO 描述文件命名。如有需要可以按组织命名规范修改 identifier 和 UUID 字段保持默认也完全可以。从系统域列表中找到Extensible Single Sign-Onpayload点击 Add Configuration Payload按钮。在填入任何值之前务必确认 iMazing 窗口顶部工具栏中只选中了 macOS。我们将要使用的部分键是 macOS 专属的如果同时选中 iOS、tvOS 或 watchOS这些键不会显示出来。配置扩展参数为指定的键填入以下值键Key值ValueExtension identifiercom.microsoft.CompanyPortalMac.ssoextensionTypeRedirectTeam identifierUBF8T346G9URLshttps://login.microsoftonline.com、https://login.microsoft.com、https://sts.windows.netScreen locked behaviorDo Not HandleAuthentication methodUser Secure Enclave KeyPlatform SSO authentication methodUserSecureEnclaveKeyUse shared device keysChecked勾选Account namepreferred_usernameFull namename关于 SecureEnclaveKey 认证方式本描述文件使用SecureEnclaveKey认证方法即使用 Secure Enclave 备份的密钥向 IdP 认证而不是用户的本地账户密码。自 2025 年 8 月起Secure Enclave 已成为所有新设备注册的默认密钥存储方式。最终描述文件示例按上述配置完成后的描述文件内容如下这也是仓库中 docs/solutions/macos/configuration-profiles/entra-sso-extension-example.mobileconfig 所采用的结构?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keyPayloadContent/key array dict keyAuthenticationMethod/key stringUserSecureEnclaveKey/string keyExtensionIdentifier/key stringcom.microsoft.CompanyPortalMac.ssoextension/string keyPayloadDisplayName/key stringExtensible Single Sign-On/string keyPayloadIdentifier/key stringcom.apple.extensiblesso.4D68D4CF-1250-4FF4-AFFB-1176DB539C49/string keyPayloadType/key stringcom.apple.extensiblesso/string keyPayloadUUID/key string4D68D4CF-1250-4FF4-AFFB-1176DB539C49/string keyPayloadVersion/key integer1/integer keyPlatformSSO/key dict keyAuthenticationMethod/key stringUserSecureEnclaveKey/string keyTokenToUserMapping/key dict keyAccountName/key stringpreferred_username/string keyFullName/key stringname/string /dict keyUseSharedDeviceKeys/key true/ /dict keyScreenLockedBehavior/key stringDoNotHandle/string keyTeamIdentifier/key stringUBF8T346G9/string keyType/key stringRedirect/string keyURLs/key array stringhttps://login.microsoftonline.com/string stringhttps://login.microsoft.com/string stringhttps://sts.windows.net/string /array /dict /array keyPayloadDisplayName/key stringPlatformSSO/string keyPayloadIdentifier/key stringcom.fleetdm.platformsso.652B07D0-2E08-45CE-9423-1FCAFFAEC390/string keyPayloadType/key stringConfiguration/string keyPayloadUUID/key string652B07D0-2E08-45CE-9423-1FCAFFAEC390/string keyPayloadVersion/key integer1/integer /dict /plist将描述文件保存到电脑上以便在下一步上传到 Fleet原文作者命名为platform-sso-settings.mobileconfig。如有需要可以在上传前对描述文件签名但这不是必需的。仓库示例中的扩展配置要点仓库自带的 entra-sso-extension-example.mobileconfig 与上文的示例相比还包含几个值得注意的差异点可作为进一步优化的参考URLs 覆盖更多云环境除https://login.microsoftonline.com、https://login.microsoft.com、https://sts.windows.net之外还额外包含https://login.partner.microsoftonline.cn、https://login.chinacloudapi.cn中国区 21Vianet 云、https://login.microsoftonline.us、https://login-us.microsoftonline.com美国政府云适用于全球多租户或特殊合规环境。EnableRegistrationDuringSetup仓库示例开启了EnableRegistrationDuringSetup用于在 Setup AssistantADE 自动化设备注册阶段启用注册这对应 Fleet 正在测试的 Simplified Setup 预览能力。AuthenticationMethod 使用Password仓库示例采用Password认证方法密码同步模式下文会单独讨论。Fleet 侧对配置描述文件的 API 支持也很完善可通过 Create configuration profile 端点上传 macOS 配置描述文件通过 Get hosts OS settings (configuration profile) 查询主机实际收到的配置从而核对描述文件是否成功下发。第三步将配置描述文件部署到主机现在我们已经有了包含目标设置的配置描述文件可以把它上传到 Fleet推送到主机并激活 Platform SSO 扩展。在你的 Fleet 服务器上选择要部署 Platform SSO 的 fleet团队。导航到Controls OS Settings Configuration profiles。点击Add profile按钮在电脑上找到platform-sso-settings.mobileconfig并上传到 Fleet。将描述文件上传到某个 fleet 后Fleet 会自动把它下发到该 fleet 中所有已注册的 macOS 主机。如果你想更精细地控制该 fleet 内哪些主机接收描述文件可以使用labels标签来定向包含或排除特定主机。从源码结构看Fleet 的 MDM 配置描述文件下发基于 Apple MDM 的InstallProfile命令流相关服务端实现集中在 server/service/apple_mdm.go 与 server/fleet/mdm.go。例如mdm.go中提到 Fleet 的 PSSO 注册令牌通过配置描述文件的RegistrationToken键下发——这也是 Fleet 自身实现 PSSO 扩展时使用的机制说明配置描述文件包括第三方 SSO 扩展的描述文件是 PSSO 体系中不可替代的交付通道。终端用户体验注册流程当 Company Portal 应用和 Platform SSO 配置描述文件都部署到主机后最终用户会收到一条Registration Required: Please register with your identity provider通知。应指导用户在鼠标悬停到通知上时点击出现的Register按钮。点击通知中的注册按钮后会出现Platform Single Sign-On Registration注册窗口。点击Continue后用户会被要求输入登录 Mac 时使用的密码这个密码可能与其 Entra ID 密码不同。接下来用户会被要求登录 Microsoft Entra ID——这一步会把用户的设备与他们的 Microsoft Entra ID 账户关联起来。最后用户会被要求启用 Company Portal 应用作为 Passkey通行密钥。通知会引导用户前往系统设置打开 Company Portal 应用旁边的开关。注册完成后员工下次在 Web 浏览器中登录 Entra ID 保护的应用时认证将完全无感不会再提示输入密码也不需要完成 MFA 挑战Platform SSO 扩展会使用 Secure Enclave 备份的密钥完成整个认证过程。注册流程背后的原理源码视角从 docs/Contributing/mdm/apple/psso.md 的序列图可以看到这一注册通知 → 注册窗口 → 登录 IdP → 启用 Passkey的用户体验背后是一套完整的设备注册与密钥分发协议设备注册Phase 1macOS 的 AppSSO 框架通过beginDeviceRegistration提供 Secure Enclave 生成的签名与加密密钥对扩展将其与注册令牌Fleet 签名 JWT即配置描述文件中的RegistrationToken一起 POST 到 Fleet 的/api/mdm/apple/psso/registration端点Fleet 按主机 UUID 解析设备并存储密钥 ID。对应源码中的PSSODeviceRegistrationRequest结构server/fleet/apple_psso.go其字段device_signing_key、device_encryption_key、signing_key_id、encryption_key_id与registration_token一一对应注册令牌的签发与校验由 server/mdm/apple/psso/regtoken/regtoken.go 中的Mint/Validate实现。离线解锁密钥下发Phase 2PSSO 2.0macOS 依次调用/api/mdm/apple/psso/nonce获取 nonce再以key_request和key_exchange两种请求类型调用/api/mdm/apple/psso/token通过 ECDH 交换建立解锁密钥。密码登录与同步Phase 3用户输入 IdP 密码后密码被加密进 embedded assertionECDH-ES/A256GCMFleet 用设备加密密钥解密出明文密码再通过 ROPGgrant_typepassword流向 IdP 验证成功后 Fleet 铸造自己的 id_tokenES256 签名JWE 加密回传给设备macOS 验证通过后同步本地账户密码并建立 SSO 会话。理解这一协议链有助于在排障时准确定位问题环节是描述文件未下发检查 Get hosts OS settings、还是设备注册失败检查注册端点日志、抑或是 IdP 侧 ROPG 凭据问题。密码同步模式Password Sync说明Platform SSO 扩展还可以配置为将本地账户凭据与 IdP 同步。要做这一点只需把配置描述文件中的AuthenticationMethod键改为Password。终端用户通过 Company Portal 应用注册后其本地账户密码会变为与 Entra ID 密码一致。需要注意使用此方法时Entra ID 保护应用的认证将不再由 Secure Enclave 备份的密钥处理这与上文主流程的UserSecureEnclaveKey模式有本质区别。仓库示例 entra-sso-extension-example.mobileconfig 正是采用的Password模式可作为此场景的直接参考模板。Fleet 自身实现 PSSO 时也正是以此为设计目标之一——让 macOS 本地账户密码与上游 IdP 凭据保持一致并在 Setup Assistant 中支持用同步密码创建用户。密码同步模式的实际限制务必提前知晓根据 Fleet 仓库设计文档 docs/Contributing/mdm/apple/psso.md 中记录的已知限制选择密码同步模式前需要评估以下几点4 小时同步窗口运行 Password SSO 的 Mac 会在现有令牌缺失、过期或超过 4 小时后的下一次解锁/登录事件中向 IdP 校验密码。这意味着密码在 IdP 侧变更后Mac 最迟可能要等到 4 小时加上用户锁屏/解锁所需的时间才会检测到变化。部分场景需要输入两次密码最常见的情形是用户回到已锁定的机器而此时他已在 IdP 侧修改过密码。需要在 IdP 开启 LDAP 或 ROPG密码同步必须由服务器侧校验密码这要求在 IdP 中启用 LDAP 或 OAuth ROPG。部分 IdP 不推荐这些方式因为涉及明文密码流转到第三方应用对某些客户而言可能存在安全政策上的顾虑。上游 IdP 的 ROPG 限制Entra 环境下需要 MFA 的用户和联合AD FS用户无法通过 ROPG 认证Okta 下 ROPG 必须在应用上显式启用且应用类型必须是 Native 或 Service。这些是上游约束不是 Fleet 的缺陷。全局配置PSSO 设置位于AppConfig上目前没有按团队per-team覆盖的能力。部署自检清单完成上述步骤后可以用以下清单快速验证部署是否成功Company Portal 是否已安装在主机详情页的Software标签页确认CompanyPortal-Installer.pkg已安装。描述文件是否已下发在Controls OS Settings Configuration profiles查看描述文件状态或通过 Get hosts OS settings (configuration profile) API 查询主机实际收到的配置描述文件。用户是否完成注册终端用户是否点击了 Registration Required 通知并完成 Entra ID 登录。Passkey 是否启用系统设置中 Company Portal 应用的 Passkey 开关是否已打开。登录体验验证用户在浏览器登录 Entra ID 保护的应用时是否不再提示密码或 MFA。小结通过 Fleet 部署 Microsoft Entra ID 的 Platform SSO本质上分三步走上传 Company Portal 应用自动策略安装→ 用 iMazing Profile Editor 构建com.apple.extensiblesso配置描述文件选择UserSecureEnclaveKey或Password认证模式→ 通过 Fleet 的Controls OS Settings上传描述文件并按需用标签控制下发范围。配置正确且用户完成一次注册后Secure Enclave 备份的密钥即可为 Entra ID 保护的应用提供无感、防钓鱼的认证体验。如果企业更看重本地密码与 IdP 密码完全一致的运维模型可以将AuthenticationMethod切换为Password但需要接受 4 小时同步窗口、依赖 IdP 侧 LDAP/ROPG 能力以及部分场景需输入两次密码等已知限制。无论选择哪种模式仓库中的 entra-sso-extension-example.mobileconfig 都是可直接对照的权威示例而 docs/Contributing/mdm/apple/psso.md 则为深入理解 PSSO 协议与 Fleet 服务端实现提供了完整的参考。【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考