使用 Fleet 部署 Apple 账户开通Apple account provisioning基于 ROPG IdP 的 macOS 本地账户创建与密码同步实战【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleetFleet 的 Apple 账户开通功能Apple account provisioning能够在你通过 Apple Business自动注册/ADE为 macOS 主机完成注册时使用终端用户的身份提供商IdP凭据自动创建 macOS 本地账户并在之后持续保持本地账户密码与 IdP 同步。它借助内置于 Fleet Desktop 应用中的 Fleet Platform SSO 扩展通过 Fleet 服务器将认证代理给任何支持 OAuth 资源所有者密码授权Resource Owner Password GrantROPG的 IdP。本文以 Okta 为例完整演示从 Okta 应用创建、Fleet 集成配置、setup experience 编排到配置描述文件上传的端到端落地流程并深入到当前开源仓库的源码实现帮助你理解其认证链路、安全边界与故障排查方式。该功能需要 Fleet Premium。如果你的 IdP 本身提供原生 Platform SSO 集成如 Okta Device Access 或 Microsoft Entra建议优先使用原生集成。Fleet 的账户开通面向的是原生集成不可用或未授权使用的场景。你得到什么以及暂时得不到什么启用 Apple 账户开通后终端用户在 Setup Assistant 期间使用其 IdP 用户名和密码进行认证macOS 使用该密码创建本地账户。本地账户密码与 IdP 保持同步。IdP 中修改密码后在登录窗口、锁屏或 FileVault 解锁界面使用新密码登录即可更新本地密码且钥匙串keychain保持完好。本地账户的短名称short name和全名full name可通过TokenToUserMapping从 IdP 属性映射得到。目前暂不提供的部分对 SaaS 应用和网站的单一登录SSO。Fleet 的扩展目前仅处理账户创建与密码同步。之所以必须使用 OAuth ROPG是因为密码同步需要 IdP 验证用户的真实密码。其他桌面密码同步产品在开通与同步时也使用同一类流程。由于 ROPG 会将用户名和密码直接发送到令牌端点因此会绕过 MFA部分组织的安全策略可能不允许这样做。前置条件Fleet Premium运行 macOS 26 或更高版本、通过 Apple Business 走 ADE 注册的 macOS 主机支持 OAuth ROPG 的 IdP本指南使用 Okta为目标 fleet 配置好的 setup experience包含 Fleet Platform SSO 扩展的 Fleet Desktop 应用可作为 Fleet 维护的应用 获取账户开通目前只能为“所有 fleetAll fleets”配置且仅支持单用户 macOS 主机。第一步在 Okta 中创建 OAuth ROPG 应用Okta 仅在 Native 应用集成上支持 Resource Owner Password 授权。登录 Okta Admin Console进入Applications Applications Create App Integration。登录方式选择OIDC - OpenID Connect应用类型选择Native Application点击Next。为应用命名例如“Fleet account provisioning”。在Grant type下勾选Resource Owner Password。在Assignments下将应用分配给将要注册 Mac 的用户或用户组然后点击Save。在应用的General选项卡中点击Client Credentials区域的Edit将Client authentication设置为Client secret点击Save。复制Client ID和Client secret在第 3 步中将其添加到 Fleet。接下来确认应用可以完成仅密码登录进入Applications Applications打开你的应用选择Sign On选项卡。确保分配给应用的认证策略允许以Password作为单一因素登录。如果策略要求 MFAROPG 请求将会失败。最后找到你的令牌 URL。Fleet 推荐使用default授权服务器因为它支持第 2 步中名称映射所用的自定义声明进入Security API Authorization Servers打开default。你的令牌 URL 是IssuerURI 加上/v1/token例如https://example.okta.com/oauth2/default/v1/token。在Access Policies选项卡中确保分配给该应用的策略规则允许Resource Owner Password授权类型。你也可以使用 Okta 的组织授权服务器https://example.okta.com/oauth2/v1/token但它不支持自定义声明因此使用TokenToUserMapping的短名称映射将不可用。第二步映射短名称与全名可选不做任何映射时macOS 会使用终端用户的 IdP 用户名作为本地账户的账户名短名称因此以fleetieexample.com登录的用户会得到fleetieexample.com作为账户名。要想获得类似fleetie这样更友好的账户名需要在 Okta 中添加一个自定义声明并在配置描述文件的TokenToUserMapping中映射它。Fleet 会将来自 IdP ID 令牌的标准email、name、preferred_username声明以及名称以account开头的任何自定义声明转发到 Mac。请相应地命名自定义声明例如accountName或accountFullName。在 Okta 中添加短名称声明进入Security API Authorization Servers打开default。在Claims选项卡中点击Add Claim然后填写Name:accountNameInclude in token type:ID Token, AlwaysValue type:ExpressionValue:String.substringBefore(user.login, )Include in:Any scope点击Create。对于全名当授予profilescope 时Fleet 默认请求openid profile email标准name声明开箱即用。如果你希望使用不同的值也可以按相同方式添加自定义的accountFullName声明。在第 5 步中你需要在配置描述文件的TokenToUserMapping字典里引用这些声明名称。第三步将 Fleet 连接到 IdP在 Fleet 中进入Settings Integrations Account provisioning。输入第 1 步得到的Token URL、Client ID和Client secret然后保存。也可以使用 GitOps 在default.yml中配置controls: apple_account_provisioning: oauth_idp_token_url: https://example.okta.com/oauth2/default/v1/token oauth_idp_client_id: 0oa12345abcdeFGHI678 oauth_idp_client_secret: # TODO: client secret (masked and non-exportable from the API)从源码结构看这一 GitOps 片段与 server/fleet/apple_psso.go 中定义的AppleAccountProvisioning结构体字段一一对应OAuthIdPTokenURL上游 OIDC 令牌端点、OAuthIdPClientID在 IdP 注册的客户端/应用 ID与OAuthIdPClientSecret。其中oauth_前缀是为将来引入其他认证方式如 LDAP预留的命名空间。Configured()方法仅在令牌 URL 与客户端 ID 非空时返回 true——client secret 不参与此检查因为写入路径保证了只要公开字段被设置就会有加密存储的 secret 与之配套。关于凭据安全apple_psso.go 的注释明确说明client secret永远不会持久化到 AppConfig JSON 中。写入时它会被剥离出来加密存储在mdm_config_assets中API 仅返回掩码后的值令牌 URL 与客户端 ID 则存储在 JSON 中。第四步将 Fleet 的 Platform SSO 应用加入 setup experience包含 Platform SSO 扩展的 Fleet Desktop 应用默认不会安装。请将其添加为 setup experience 软件使其在 Setup Assistant 期间、用户到达登录界面之前完成安装在 Fleet 中进入目标 fleet 的Software页面选择Add software打开Fleet-maintained选项卡添加Fleet Desktop。进入Controls Setup experience Install software勾选 Fleet Desktop 应用使其在 setup experience 期间安装。同时确认Controls Setup experience Users中的End user account已选择Admin或Standard以确保在设备上创建本地用户账户。如果选择了None用户完成注册后会遇到灰色登录界面其凭据无法生效。第五步创建并上传配置描述文件扩展由单个包含 2 个 payload 的配置描述文件激活一个Extensible Single Sign-Onpayload 和一个Associated Domainspayload。从仓库中的 示例描述文件 开始将其中所有fleet.example.com替换为你 Fleet 服务器的域名。在 Extensible Single Sign-On payload 中ExtensionIdentifier:com.fleetdm.fleet-desktop.pssoextensionTeamIdentifier:8VBZ3948LU。请原样使用这些值。ExtensionData BaseURL和URLs:你的 Fleet 服务器 URL。RegistrationToken:$FLEET_VAR_PSSO_DEVICE_REGISTRATION_TOKEN。Fleet 会在描述文件投递到每台主机时用每个设备唯一的注册令牌替换此变量。EnableRegistrationDuringSetup和UseSharedDeviceKeys:均为true使用户在 Setup Assistant 期间完成注册。TokenToUserMapping:将 macOS 账户字段映射到 Mac 收到的令牌中的声明名称。示例描述文件将短名称映射到第 2 步的accountName声明将全名映射到标准name声明keyTokenToUserMapping/key dict keyAccountName/key stringaccountName/string keyFullName/key stringname/string /dict如果跳过了第 2 步请删除AccountName键或整个TokenToUserMapping字典macOS 将使用 IdP 用户名作为账户名。$FLEET_VAR_PSSO_DEVICE_REGISTRATION_TOKEN只允许出现在 Fleet SSO 扩展 payload 的RegistrationToken键中。Fleet 在查看已投递的InstallProfile命令时会对该令牌进行脱敏因此它永远不会暴露在 UI 或 API 中。在 Associated Domains payload 中两个应用标识符8VBZ3948LU.com.fleetdm.fleet-desktop和8VBZ3948LU.com.fleetdm.fleet-desktop.pssoextension都必须列出authsrv:加上你的 Fleet 服务器域名。将描述文件上传到目标 fleet 的Controls OS settings Custom settings。不要使用标签label来限定此描述文件的作用范围。带标签的描述文件可能无法在 Setup Assistant 前及时投递如果发生这种情况用户将不会被提示登录。从源码看注册令牌与设备注册机制注册令牌并非一个简单的占位符而是由 Fleet 签名、绑定到特定主机的 JWT。server/fleet/apple_psso.go 中的PSSODeviceRegistrationRequest记录了设备注册请求的完整结构扩展在设备上基于 Secure Enclave 生成签名 加密两对密钥对提交公钥及其 kidkey ID以及RegistrationToken。在 Password 模式下这是纯密钥注册——用户身份是在每次密码登录的令牌端点上才确立的。PSSOKey结构体apple_psso.go按 kid密钥字节的 base64 SHA-256索引已注册设备的公钥服务器据此在扩展携带带该 kid 的 JWT 时解析出所属设备。一台主机可持有同类型的多个密钥重新注册会新增密钥而不会使旧密钥失效。从 server/service/integration_mdm_apple_psso_test.go 的端到端测试可见空令牌、伪造的非 Fleet 签名令牌均会被拒绝注册成功注册后设备会持有签名与加密两把密钥require.Len(t, keys, 2)。密码登录链路与声明转发集成测试中的pssoMockIdPintegration_mdm_apple_psso_test.go是 OAuth2 ROPG 令牌端点的替身Fleet 的 PSSO 登录流程向它 POSTgrant_typepassword并从返回的id_token中读取用户声明。测试验证L181-L205设备最终拿到的 ID 令牌由 Fleet 以自己的 JWKS 签发其中sub为 IdP 主题、email/name/preferred_username被转发而accountName这类以account前缀命名的自定义声明同样被转发供描述文件中的TokenToUserMapping映射为 macOS 短名称——这与文档中“名称以account开头的自定义声明会被转发”的说明完全吻合。测试还覆盖了密码加密传输模式L207-L220在EncryptOnWire模式下普通密码不再出现在断言assertion负载中而是放入加密断言内grant_type变为urn:ietf:params:oauth:grant-type:jwt-bearer。此外PSSOClaims结构体apple_psso.go中的RefreshToken与ExpiresIn字段承载上游 IdP 的 OAuth 令牌响应字段设备将刷新令牌视为不透明值用于静默 SSO 续期ExpiresIn为访问/刷新令牌的生命周期秒。终端用户体验用户开启 Mac设备通过自动注册完成 ADE 注册。终端用户认证是可选的若已启用用户先用 IdP 凭据登录。Setup experience 安装 Fleet Desktop 应用并投递配置描述文件。在 Setup Assistant 期间、Fleet 的 setup experience 窗口关闭后用户被提示使用其 IdP 用户名和密码登录。macOS 创建本地账户。密码即用户的 IdP 密码账户名与全名来自已配置的TokenToUserMapping如果配置了的话。账户创建界面会显示出来但此时值被锁定用户无法编辑。设置完成后密码同步按如下方式工作用户在 IdP 中修改密码然后用新密码登录或解锁时本地密码同步并出现确认通知。钥匙串保持完好。修改密码后用户继续使用旧密码则该密码在 Mac 下一次与 IdP 检入check in前最长 4 小时仍然可用。之后macOS 会在下次桌面登录时提示用户同步。FileVault 解锁适用于同步后的密码。如果 Fleet 服务器不可达用户永远不会被锁在门外。现有本地密码在连接恢复前一直有效。建议在通过 IdP 完成密码修改后指导用户立即用新密码锁定并解锁其 Mac以便立刻同步 Mac 密码而不是依赖稍后自动发生。从源码结构看密码同步的“检入/离线解锁”机制有专门的支撑实现PSSOSettingsapple_psso.go是按请求组装的解析后配置包括 Fleet 自身的基础 URL作为令牌签发者并用于构建 AASA/JWKS URL、上游 IdP 令牌端点、客户端 ID/secret以及默认的openid profile emailscope 字符串。集成测试中的KeyRequest/KeyExchange用例L222-L229验证了离线解锁所需的密钥请求与 ECDH 密钥交换流程——即使 Fleet 服务器暂时不可达设备仍能利用已下发的密钥完成解锁。故障排查用户在 Setup Assistant 期间没有被提示登录。确认 Fleet Desktop 应用已设置为 setup experience 软件第 4 步、描述文件已上传到同一 fleet 且未做标签限定第 5 步并且主机运行的是 macOS 26 或更高版本。使用有效凭据登录失败。检查 Okta 应用配置第 1 步。必须启用Resource Owner Password授权客户端认证必须设置为Client secret用户必须已分配给该应用且应用的认证策略必须允许仅密码登录。同时确认 Fleet 中的令牌 URL 指向正确的授权服务器且其访问策略允许密码授权。账户名是完整的电子邮件地址。accountName声明没有到达 Mac。确认自定义声明存在于与令牌 URL 相同的授权服务器上自定义声明需要自定义授权服务器而不是组织授权服务器确认它包含在 ID 令牌中并且名称以account开头。用户被提示输入之前的密码。有时在用户注销后重新登录而非锁定/解锁 Mac时用户会在桌面被提示输入之前的密码。这是预期行为用户应输入之前的密码来完成该过程。如果他们无法完成此过程FileVault 密码可能不会与其新密码同步。进一步阅读Setup experienceDeploying Platform SSO with Okta Device Access示例 Platform SSO 配置描述文件Apple 账户开通配置的结构体定义与凭据存储说明Apple Platform SSO 端到端集成测试【免费下载链接】fleetOpen device management项目地址: https://gitcode.com/GitHub_Trending/fl/fleet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考