Apereo CAS 中的 OAuth 2.0 设备授权流（Device Authorization Grant）：无浏览器设备的令牌签发实战指南

后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载导读本文聚焦 Apereo CAS 中 OAuth 2.0设备授权授予Device Authorization Grant旧称 Device Flow的完整实现与使用方式。该协议扩展让 Apple TV 这类没有浏览器、或仅具备有限输入能力的设备如可向 YouTube 频道推流的硬件编码器也能安全地获取访问令牌。读完本文你将掌握 CAS 设备流的两个核心调用方式申请 device code / user code、用 device code 换取 access token、与设备流相关的全部可配置参数令牌有效期、轮询间隔、用户码长度等以及底层控制器、票据工厂与异常映射的源码级工作原理。一、什么是 OAuth 2.0 设备授权授予OAuth 2.0 设备授权授予是标准 OAuth 2.0 的一个扩展专门解决没有浏览器或输入能力受限的设备如何完成授权的问题。典型场景包括Apple TV 等智能电视应用可向 YouTube 频道推流的硬件视频编码器打印机、路由器等 IoT 设备。其核心思路是设备本身不做用户交互而是先向授权服务器申请一个device code设备码和一个user code用户码用户在另一台具备浏览器的设备如手机、电脑上打开验证页面、输入 user code 完成授权设备随后用 device code 轮询令牌端点直到用户批准后拿到 access token。在 Apereo CAS 中该流程定义于官方文档 OAuth-ProtocolFlow-DeviceAuthorization.md涉及两个端点调用方式整理如下端点参数响应/oauth2.0/accessTokenresponse_typedevice_codeclient_idID设备授权 URL、device code 与 user code/oauth2.0/accessTokenresponse_typedevice_codeclient_idIDcodeDEVICE_CODE用户码被批准后返回新的 access token二、两步式设备流调用详解第一步申请设备码与用户码设备首先向 CAS 的令牌端点发起首次请求使用response_typedevice_code表明这是一次设备授权申请并携带注册过的client_idGET/POST /oauth2.0/accessToken ?response_typedevice_code client_idCLIENT_IDCAS 在收到该请求后会生成一对凭证device code设备码设备自身持有用于后续轮询换取令牌相当于设备会话凭证user code用户码展示给用户、供其在另一台设备上输入的短码verification_uri验证 URL用户需要用浏览器访问的授权页面地址。从源码看这三个响应对应的参数名定义在 OAuth20Constants.java 中verification_uriDEVICE_VERIFICATION_URI设备验证页 URLuser_codeDEVICE_USER_CODE用户码device_codeDEVICE_CODE设备码intervalDEVICE_INTERVAL建议的轮询间隔。在 CAS 实现里response_typedevice_code与标准的grant_typeurn:ietf:params:oauth:grant-type:device_code常量定义于 OAuth20GrantTypes.java是等价的。负责识别该请求的提取器 AccessTokenDeviceCodeResponseRequestExtractor.java 的supports方法会同时检查这两种写法val validRequest OAuth20Utils.isResponseType(responseType, OAuth20ResponseTypes.DEVICE_CODE) || OAuth20Utils.isGrantType(grantType, OAuth20GrantTypes.DEVICE_CODE); return validRequest StringUtils.isNotBlank(clientId);即只要请求中带有response_typedevice_code或grant_typeurn:ietf:params:oauth:grant-type:device_code且client_id非空该请求即被判定为设备流申请。第二步用设备码轮询换取访问令牌设备随后以固定间隔向同一端点发起轮询携带client_id与第一步拿到的device_code参数名为codeGET/POST /oauth2.0/accessToken ?response_typedevice_code client_idCLIENT_ID codeDEVICE_CODE只有当用户已经完成 user code 的批准后CAS 才会返回新的access token以及按注册服务配置决定是否生成的 refresh token。AccessTokenDeviceCodeResponseRequestExtractor在提取请求时会根据client_id定位注册服务OAuth20Utils.getRegisteredOAuthServiceByClientId解析 scopes 并执行服务访问策略校验随后把deviceCode一并写入AccessTokenRequestContext交由 OAuth20DefaultTokenGenerator.java 完成令牌签发。三、设备流的错误处理与协议语义设备流轮询过程中用户可能尚未批准或已拒绝也可能设备轮询过快。CAS 在 OAuth20AccessTokenEndpointController.java 中对设备流异常做了标准映射异常类返回的 OAuth 错误码语义InvalidOAuth20DeviceTokenExceptionaccess_denied无法识别/提取设备令牌请求UnapprovedOAuth20DeviceUserCodeExceptionauthorization_pending用户码尚未批准设备应继续轮询ThrottledOAuth20DeviceUserCodeApprovalExceptionslow_down请求过于频繁被限流应放慢轮询速度其他未匹配异常invalid_grant无效或未授权的授予其中authorization_pendingAUTHORIZATION_PENDING、slow_downSLOW_DOWN、access_deniedACCESS_DENIED等常量同样定义在 OAuth20Constants.java 中与 RFC 8628 的设备授权扩展错误语义保持一致。对应异常类型位于 device 包下并由同目录的校验器在令牌签发前抛出。四、用户码批准流程与端点设备流的关键一环是用户在另一台设备上完成授权。CAS 提供了专用的用户码批准端点/oauth2.0/device由 OAuth20DeviceUserCodeApprovalEndpointController.java 实现GET/oauth2.0/device渲染用户码输入页面视图oauthDeviceCodeApprovalViewPOST/oauth2.0/device提交表单参数usercodeCAS 会通过OAuth20DeviceUserCodeFactory的normalizeUserCode规范化用户码并定位对应票据若该用户码已被批准则返回codeapproved错误提示视图仍为批准页获取当前登录用户OAuth20Utils.getAuthenticatedUserProfile与票据授予票据TGT将认证信息写入用户码票据deviceUserCode.setAuthentication(...)、标记setUserCodeApproved(true)调用ticketRegistry.updateTicket(...)持久化并渲染成功视图oauthDeviceCodeApprovedView。如果提交的用户码为空或票据查找失败则返回codenotfound错误。整个批准流程完成后设备端下一次轮询即可拿到 access token。五、设备流相关配置参数设备流的有效期、轮询频率与用户码长度等行为由 CAS 的 OAuth 配置节cas.authn.oauth.*中的两个嵌套配置对象控制其默认值定义于配置模型 OAuthDeviceTokenProperties.java 与 OAuthDeviceUserCodeProperties.java并挂载在 OAuthProperties.java 下。设备令牌device token配置cas.authn.oauth.device-token配置项默认值说明cas.authn.oauth.device-token.max-time-to-live-in-secondsPT5M设备令牌的硬超时时间到期即被销毁cas.authn.oauth.device-token.refresh-intervalPT15S设备轮询间隔。客户端应按此速率向令牌端点 POST尝试获取 access tokencas.authn.oauth.device-token.storage-nameoauthDeviceTokensCache设备令牌在底层 ticket registry 中使用的存储对象名其中refresh-interval即响应中interval字段的建议来源客户端应按照该间隔进行轮询避免触发slow_down限流。用户码user code配置cas.authn.oauth.device-user-code配置项默认值说明cas.authn.oauth.device-user-code.max-time-to-live-in-secondsPT1M用户码的硬超时时间到期即失效cas.authn.oauth.device-user-code.user-code-length8生成用户码的长度字符数cas.authn.oauth.device-user-code.storage-nameoauthDeviceUserCodesCache用户码在底层 ticket registry 中使用的存储对象名一个贴近实际的最小 YAML 配置示例cas: authn: oauth: device-token: max-time-to-live-in-seconds: PT10M refresh-interval: PT30S device-user-code: max-time-to-live-in-seconds: PT2M user-code-length: 10注意设备令牌与用户码均以CAS Ticket票据的形式存放在 ticket registry 中因此有效期策略也支持按注册服务覆盖。从 OAuth20DefaultDeviceTokenFactory.java 的实现可以看到生成 device code 时会调用OAuth20DeviceTokenUtils.determineExpirationPolicyForService(...)按服务解析其专属过期策略对应服务注册模型中的策略类型为 RegisteredServiceOAuthDeviceTokenExpirationPolicy.java。六、从源码看设备流的完整调用链设备流在 CAS 中的执行链路可概括为请求入口POST /oauth2.0/accessToken命中 OAuth20AccessTokenEndpointController先由verifyAccessTokenRequest遍历注册的accessTokenGrantRequestValidators校验请求合法性请求识别AccessTokenDeviceCodeResponseRequestExtractor.supports(...)判断response_typedevice_code或grant_typeurn:ietf:params:oauth:grant-type:device_code请求提取extractRequest(...)解析client_id、定位注册服务、解析 scopes、构建匿名认证上下文并携带device_code令牌生成OAuth20DefaultTokenGenerator.generate(...)依据已批准的 device code 生成 access token及可选的 refresh token响应编码OAuth20DefaultAccessTokenResponseGenerator输出包含access_token、token_type、expires_in等字段的标准响应异常兜底未批准返回authorization_pending过快轮询返回slow_down无效设备码返回access_denied其余返回invalid_grant。用户侧则在GET/POST /oauth2.0/device完成 user code 的提交与批准二者配合构成完整的授权闭环。上述链路均有对应的测试用例覆盖例如 OAuth20AccessTokenEndpointControllerTests.java、AccessTokenDeviceCodeResponseRequestExtractorTests.java、OAuth20DeviceCodeResponseTypeRequestValidatorTests.java 与 OAuth20DeviceUserCodeApprovalEndpointControllerTests.java可作为验证行为与排查问题的参考。七、使用前提与注意事项依赖模块设备流功能位于cas-server-support-oauth模块需要先引入该依赖相关配置类均标注了RequiresModule(name cas-server-support-oauth)。客户端注册请求中使用的client_id必须在 CAS 服务注册表中存在且具备访问权限否则提取器会因定位不到注册服务而失败。刷新令牌是否随 access token 一并签发 refresh token取决于注册服务配置中的generateRefreshToken开关见AccessTokenDeviceCodeResponseRequestExtractor中generateRefreshToken(registeredService ! null registeredService.isGenerateRefreshToken())一行。安全提示设备流本质上是用户码 设备码双因素式授权建议按需收紧max-time-to-live-in-seconds避免设备码长时间有效同时引导设备遵守interval轮询防止触发slow_down限流。八、总结Apereo CAS 完整实现了 OAuth 2.0 设备授权授予设备通过/oauth2.0/accessToken端点以response_typedevice_code申请设备码与用户码用户通过/oauth2.0/device批准用户码设备再以codeDEVICE_CODE轮询换取 access token。其有效期、轮询间隔、用户码长度均可通过cas.authn.oauth.device-token与cas.authn.oauth.device-user-code两个配置节精细控制底层以 CAS 票据机制存储、支持按服务定制过期策略并遵循authorization_pending、slow_down、access_denied等标准错误语义可安全地服务于 Apple TV、硬件编码器等无浏览器设备场景。赞分享后端认证鉴权单点登录【免费下载链接】casApereo CAS - Identity Single Sign On for all earthlings and beyond.项目地址https://gitcode.com/gh_mirrors/ca/cas点击查看免费下载相关推荐Apereo CAS OAuth 2.0 授权码流程Authorization Code与 PKCE 扩展实战指南Apereo CAS OAuth 2.0 授权码流程Authorization Code与 PKCE 扩展实战指南 导读 授权码Authorization后端认证鉴权单点登录Apereo CAS OAuth 2.0 Refresh Token 授权流程Refresh Token Grant完全解析Apereo CAS OAuth 2.0 Refresh Token 授权流程Refresh Token Grant完全解析 本文围绕 Apereo CAS后端认证鉴权单点登录Apereo CAS OpenID Connect JWT Bearer 授权模式JWT Authorization Grant接入指南Apereo CAS OpenID Connect JWT Bearer 授权模式JWT Authorization Grant接入指南 JWT Beare后端认证鉴权单点登录创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考