本指南面向命令行工具、电视类应用、嵌入式设备，或其他不适合在本机输入密码的客户端。OAuth 设备码流程允许设备先申请一组短码，引导用户在另一台带浏览器的设备上完成登录和授权，然后设备端轮询 token endpoint，直到 identity 可以签发令牌。

能力摘要

阶段	运行时端点	发生什么
请求设备授权	discovery 中的 OIDC device_authorization_endpoint	设备获得 device_code、user_code、验证地址、过期时间和轮询间隔。
用户确认	/device 或 discovery 返回的验证地址	用户输入或确认 user code，完成登录，并批准或拒绝请求。
轮询令牌	使用 device-code grant 调用 OIDC token endpoint	设备持续轮询，直到用户批准、拒绝、代码过期，或返回令牌。

前置条件

该 native 客户端已启用 DeviceFlowEnabled。当移动/原生应用客户端启用该能力后，支持的 grant posture 会变为 device_code 加 refresh_token。

推荐运行时流程

第 1 步：发现运行时端点

读取 UserPool issuer 的 discovery document，并使用其中发布的端点值，不要手工假设路径。

重点关注 discovery 响应中的 device_authorization_endpoint、token_endpoint 和 issuer 信息。

第 2 步：申请 device code

设备通过 device authorization endpoint 发起流程，提交 native 客户端标识和所需 scopes。

成功响应通常包含以下值：

第 3 步：向用户展示 user code

在设备上展示 user_code 和验证地址。如果响应中有 verification_uri_complete，建议以二维码或直接链接形式展示，减少用户手动输入短码的成本。

当用户打开验证页后，identity 会规范化短码、将其关联到授权请求，并把用户送入正常登录和授权确认路径。如果用户批准请求，identity 会为最初的 device code 完成设备授权状态。

第 4 步：轮询 token endpoint

设备使用 device code grant 轮询 token endpoint。请遵守设备授权响应中返回的 interval。

在用户尚未完成批准前，token endpoint 可能返回 pending 类响应。请按返回的轮询间隔继续请求，直到拿到令牌或遇到终态错误。

令牌响应

用户批准后，token endpoint 会返回该 native 客户端上下文下的标准令牌响应。

字段	含义
access_token	设备应用调用受保护 API 时使用的令牌。
id_token	请求 openid 时返回的已批准用户 OIDC 身份令牌。
refresh_token	当客户端和 scopes 允许刷新行为时返回，通常与 offline_access 搭配。
expires_in	access token 的有效期，单位为秒。
token_type	通常为 Bearer。

管理 API

管理目标	暴露动作	最值得关注的请求字段
创建可使用设备码流程的 native 客户端	CreateUserPoolClient	UserPoolUid、Name、ClientType、DeviceFlowEnabled
后续启用或关闭设备码流程	UpdateUserPoolClient	UserPoolUid、ClientUid、DeviceFlowEnabled
查看客户端配置	GetUserPoolClient、ListUserPoolClients	ClientUid、ClientType、grant posture、令牌设置

运营注意事项

安全注意事项

下一步