openid-connect

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenID Connect (OIDC)

OIDC extends OAuth 2.0 to provide Identity. While OAuth handles "Access" (Authorization), OIDC handles "Who are you?" (Authentication).

OIDC 扩展了 OAuth 2.0 以提供身份认证能力。OAuth 负责处理“访问权限”（授权），而 OIDC 负责处理“你是谁？”（身份验证）。

When to Use

使用场景

Single Sign-On (SSO): One login for multiple apps.
User Profile: Getting
```
name
```
,
```
email
```
,
```
picture
```
from a provider.
Enterprise Identity: Connecting to Active Directory via OIDC.

单点登录（SSO）：一次登录即可访问多个应用。
用户信息获取：从身份提供商处获取
```
name
```
、
```
email
```
、
```
picture
```
等信息。
企业身份集成：通过 OIDC 连接到 Active Directory。

Quick Start

快速开始

http

// Request
GET /authorize?
  response_type=code&
  scope=openid profile email&  <-- 'openid' scope triggers OIDC
  client_id=...&
  redirect_uri=...

// Token Response
{
  "access_token": "SlAV32hkKG...", // For API access
  "id_token": "eyJ0eXKiOiJK...",   // JWT containing User Profile
  "expires_in": 3600
}

http

// 请求
GET /authorize?
  response_type=code&
  scope=openid profile email&  <-- 'openid' 作用域会触发 OIDC 流程
  client_id=...&
  redirect_uri=...

// 令牌响应
{
  "access_token": "SlAV32hkKG...", // 用于 API 访问
  "id_token": "eyJ0eXKiOiJK...",   // 包含用户信息的 JWT
  "expires_in": 3600
}

Core Concepts

核心概念

ID Token

A JSON Web Token (JWT) that contains claims (assertions) about the authentication event and the user.

一种 JSON Web Token (JWT)，包含关于身份验证事件和用户的声明（断言）。

UserInfo Endpoint

UserInfo 端点

A standard OAuth protected endpoint (

/userinfo

) where you can send the Access Token to get more user details.

一个标准的 OAuth 受保护端点 (

/userinfo

)，你可以在此发送 Access Token 以获取更多用户详细信息。

Scopes

作用域（Scopes）

```
openid
```
: Required to use OIDC.
```
profile
```
: Request access to name, picture, etc.
```
email
```
: Request access to email.

```
openid
```
：使用 OIDC 必须包含的作用域。
```
profile
```
：请求访问用户姓名、头像等信息。
```
email
```
：请求访问用户邮箱。

Common Patterns

常见模式

Discovery Endpoint

发现端点

/.well-known/openid-configuration

. A JSON file that lists the issuer, authorization endpoint, token endpoint, and public keys (JWKS) automatically.

/.well-known/openid-configuration

。这是一个 JSON 文件，会自动列出颁发者、授权端点、令牌端点以及公钥（JWKS）等信息。

Best Practices

最佳实践

Do:

Validate the ID Token Signature (using JWKS).
Check the Audience (
```
aud
```
) claim matches your Client ID.
Check the Issuer (
```
iss
```
) claim matches the provider.
Use Nonce to prevent replay attacks.

Don't:

Don't treat the Access Token as an ID Token (Access Tokens are opaque strings in standard OAuth, though often JWTs in practice).
Don't accept unsigned ID tokens (algorithm
```
none
```
).

建议：

验证ID Token 签名（使用 JWKS）。
检查受众 (
```
aud
```
) 声明是否与你的客户端 ID 匹配。
检查颁发者 (
```
iss
```
) 声明是否与身份提供商一致。
使用Nonce防止重放攻击。

不建议：

不要将 Access Token 当作 ID Token 使用（标准 OAuth 中 Access Token 是不透明字符串，尽管实际中常为 JWT）。
不要接受未签名的 ID Token（算法
```
none
```
）。

Troubleshooting

故障排查

Error	Cause	Solution
`id_token missing`	Scope `openid` not requested.	Add `openid` to scopes.
`Signature Invalid`	Wrong Public Key.	Refresh JWKS from the discovery endpoint.

错误信息	原因	解决方案
`id_token missing`	未请求 `openid` 作用域	在作用域中添加 `openid` 。
`Signature Invalid`	公钥错误	从发现端点刷新 JWKS。

openid-connect

Original

Translation

OpenID Connect (OIDC)

OpenID Connect (OIDC)

When to Use

使用场景

Quick Start

快速开始

Core Concepts

核心概念

ID Token

ID Token

UserInfo Endpoint

UserInfo 端点

Scopes

作用域（Scopes）

Common Patterns

常见模式

Discovery Endpoint

发现端点

Best Practices

最佳实践

Troubleshooting

故障排查

References

参考资料