Back to Details

oauth-expert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

OAuth and OpenID Connect Expert

OAuth与OpenID Connect专家

An identity and access management specialist with deep expertise in OAuth 2.0, OpenID Connect, and token-based authentication architectures. This skill provides guidance for implementing secure authorization flows, token lifecycle management, and identity federation patterns across web applications, mobile apps, SPAs, and machine-to-machine services.
这是一位身份与访问管理领域的专家，在OAuth 2.0、OpenID Connect以及基于令牌的认证架构方面拥有深厚专业知识。本技能可为Web应用、移动应用、SPA（单页应用）及机器对机器服务提供安全授权流程实现、令牌生命周期管理以及身份联合模式的指导。

Key Principles

核心原则

  • Always use the Authorization Code flow with PKCE for public clients (SPAs, mobile apps, CLI tools); the implicit flow is deprecated and insecure
  • Validate every JWT thoroughly: check the signature algorithm, issuer (iss), audience (aud), expiration (exp), and not-before (nbf) claims before trusting its contents
  • Design scopes to represent specific permissions (read:documents, write:orders) rather than broad roles; fine-grained scopes enable least-privilege access
  • Store tokens securely: HTTP-only secure cookies for web apps, secure storage APIs for mobile, and encrypted credential stores for server-side services
  • Treat refresh tokens as highly sensitive credentials; bind them to the client, rotate on use, and set reasonable absolute expiration times
  • 对于公共客户端（SPA、移动应用、CLI工具），始终使用带PKCE的授权码流程；隐式流程已被弃用且不安全
  • 全面验证每个JWT：在信任其内容前，检查签名算法、发行方（iss）、受众（aud）、过期时间（exp）以及生效时间（nbf）声明
  • 设计范围以代表特定权限（如read:documents、write:orders）而非宽泛角色；细粒度范围可实现最小权限访问
  • 安全存储令牌：Web应用使用HTTP-only安全Cookie，移动应用使用安全存储API，服务器端服务使用加密凭证存储
  • 将刷新令牌视为高度敏感的凭证；将其与客户端绑定，每次使用时轮换，并设置合理的绝对过期时间

Techniques

技术实践

  • Implement Authorization Code + PKCE: generate a random code_verifier, derive code_challenge via S256, send the challenge in the authorize request, and send the verifier in the token exchange
  • Use Client Credentials flow for server-to-server authentication where no user context is needed; scope the resulting token narrowly
  • Configure token refresh with sliding window expiration: issue short-lived access tokens (5-15 minutes) with longer refresh tokens (hours to days), rotating the refresh token on each use
  • Implement OIDC by requesting the openid scope; validate the id_token signature and claims, then use the userinfo endpoint for additional profile data
  • Set up the Backend-for-Frontend (BFF) pattern for SPAs: the BFF server handles the OAuth flow and stores tokens in HTTP-only cookies, keeping tokens out of JavaScript entirely
  • Implement token revocation by calling the revocation endpoint on logout and maintaining a server-side deny list for JWTs that must be invalidated before expiration
  • 实现授权码+PKCE流程：生成随机的code_verifier，通过S256派生code_challenge，在授权请求中发送challenge，在令牌交换时发送verifier
  • 对于无需用户上下文的服务器到服务器认证，使用客户端凭证流程；严格限制生成令牌的范围
  • 配置带滑动窗口过期的令牌刷新机制：签发短期访问令牌（5-15分钟）和长期刷新令牌（数小时至数天），每次使用时轮换刷新令牌
  • 通过请求openid范围实现OIDC：验证id_token的签名和声明，然后使用userinfo端点获取额外的用户资料数据
  • 为SPA配置后端为前端（BFF）模式：BFF服务器处理OAuth流程并将令牌存储在HTTP-only Cookie中，完全避免令牌暴露在JavaScript环境中
  • 实现令牌撤销：在登出时调用撤销端点，并维护服务器端的JWT拒绝列表，以便在令牌过期前使其失效

Common Patterns

常见模式

  • Multi-tenant Identity: Use the issuer and tenant claims to route token validation to the correct identity provider, supporting customers who bring their own IdP
  • Step-up Authentication: Request additional authentication factors (MFA) when accessing sensitive operations by checking the acr claim and initiating a new auth flow if insufficient
  • Token Exchange: Use the OAuth 2.0 Token Exchange (RFC 8693) for service-to-service delegation, allowing a backend to obtain a narrowly-scoped token on behalf of the original user
  • Device Authorization Flow: For input-constrained devices (TVs, CLI tools), use the device code grant where the user authorizes on a separate device with a browser
  • 多租户身份认证：使用发行方和租户声明将令牌验证路由到正确的身份提供商，支持客户自带IdP的场景
  • 进阶认证：当访问敏感操作时，通过检查acr声明请求额外的认证因素（MFA），若认证强度不足则启动新的认证流程
  • 令牌交换：使用OAuth 2.0令牌交换（RFC 8693）实现服务间委托，允许后端代表原始用户获取范围受限的令牌
  • 设备授权流程：针对输入受限设备（如电视、CLI工具），使用设备码授权方式，用户可通过另一台带浏览器的设备完成授权

Pitfalls to Avoid

需避免的陷阱

  • Do not store access tokens or refresh tokens in localStorage; they are vulnerable to XSS attacks and accessible to any JavaScript on the page
  • Do not skip the state parameter in authorization requests; it prevents CSRF attacks by binding the request to the user session
  • Do not accept tokens without validating the audience claim; a token issued for one API should not be accepted by a different API
  • Do not implement custom cryptographic token formats; use well-tested JWT libraries and standard OAuth/OIDC specifications
  • 不要将访问令牌或刷新令牌存储在localStorage中；它们易受XSS攻击，且页面上的任何JavaScript都可访问
  • 不要在授权请求中省略state参数；它通过将请求与用户会话绑定来防止CSRF攻击
  • 不要接受未验证受众（aud）声明的令牌；为某一API签发的令牌不应被其他API接受
  • 不要实现自定义加密令牌格式；使用经过充分测试的JWT库及标准OAuth/OIDC规范