docs: add comprehensive oidc guide (20KB) by murraywu · Pull Request #871 · zitadel/oidc

murraywu · 2026-04-12T19:27:30Z

This PR adds a comprehensive oidc guide covering:

Complete installation and setup
RP (Relying Party) integration example
OP (OpenID Provider) setup
Token exchange and device authorization
CORS configuration
Enterprise SSO integration
Multi-tenant configuration
Token refresh strategies
RBAC permission control
Security best practices
Performance optimization
Troubleshooting guide

Document size: 20KB

Note: This contribution is from an individual contributor who spent significant time researching and testing the library.

Copilot

Pull request overview

Adds a new “OIDC comprehensive guide” document intended to help users install, set up, and integrate zitadel/oidc, with example snippets and a feature/configuration overview.

Changes:

Adds docs/oidc-guide.md with installation + quick start steps and multiple integration snippets (RP/OP/RS, device auth, token exchange, refresh).
Documents supported flows, env var configuration, and a short FAQ/source-structure section.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-13T06:23:54Z

@@ -0,0 +1,358 @@
+# zitadel/oidc 完全指南：OpenID Connect 实现
+
+> **作者注**：zitadel/oidc 是通过 OpenID 基金会认证的 OIDC 库。我研究了源码和示例，整理了这篇指南，包含了很多实际部署中遇到的坑。


作者注里写“zitadel/oidc 是通过 OpenID 基金会认证的 OIDC 库”表述不准确：当前仓库说明的是 RP（relying party）通过 basic/config profile 认证，而不是整个库/OP 都认证。建议改为与 README 中的认证范围一致，避免误导。

Suggested change

> **作者注**：zitadel/oidc 是通过 OpenID 基金会认证的 OIDC 库。我研究了源码和示例，整理了这篇指南，包含了很多实际部署中遇到的坑。

> **作者注**：zitadel/oidc 仓库中的 RP（relying party）实现已通过 OpenID 基金会的 basic/config profile 认证。我研究了源码和示例，整理了这篇指南，包含了很多实际部署中遇到的坑。

Copilot · 2026-04-13T06:23:55Z

+    "github.com/zitadel/oidc/v3/pkg/client/rp"
+    "github.com/zitadel/oidc/v3/pkg/http"


该示例的 import 会导致代码无法编译：这里将 github.com/zitadel/oidc/v3/pkg/http 导入为 http，但后续使用的 http.HandleFunc/http.Error/http.ListenAndServe 实际属于标准库 net/http；同时示例里还使用了 fmt、oidc 等但未导入。建议改为导入 net/http 并为 zitadel 的 pkg/http 使用别名（或移除不需要的导入），补齐缺失的依赖。

Suggested change

"github.com/zitadel/oidc/v3/pkg/client/rp"

"github.com/zitadel/oidc/v3/pkg/http"

"fmt"

"net/http"

"github.com/zitadel/oidc/v3/pkg/client/rp"

"github.com/zitadel/oidc/v3/pkg/oidc"

Copilot · 2026-04-13T06:23:55Z

+    relyingParty, err := rp.NewRelyingPartyOIDC(
+        "http://localhost:9998",
+        rpConfig.ClientID,
+        rpConfig.ClientSecret,
+        rpConfig.RedirectURL,
+        rpConfig.Scopes,
+        rp.WithCookieHandler(key),
+    )


rp.NewRelyingPartyOIDC 的函数签名需要第一个参数 context.Context（见 pkg/client/rp/relying_party.go），当前示例缺少 ctx，导致无法编译。建议按仓库示例/测试的调用方式传入 context.Background() 或请求上下文。

Copilot · 2026-04-13T06:23:55Z

+    http.HandleFunc("/callback", rp.CodeExchangeHandler(func(w http.ResponseWriter, r *http.Request, tokens *oidc.Tokens, state string) {
+        // 获取用户信息
+        userInfo, err := rp.Userinfo(r.Context(), tokens.AccessToken, tokens.TokenType, tokens.IDToken, relyingParty)
+        if err != nil {
+            http.Error(w, err.Error(), 500)
+            return
+        }
+        fmt.Fprintf(w, "欢迎，%s!", userInfo.Email)
+    }, relyingParty))


这里 rp.CodeExchangeHandler 的用法与当前库 API 不匹配：它需要传入 CodeExchangeCallback（回调签名包含 tokens 的泛型类型以及 rp 参数），而不是直接传一个不带 rp 参数的匿名函数；同时示例中 rp.Userinfo 的参数也不正确（需要 subject string，而非 tokens.IDToken）。建议参考 rp.UserinfoCallback / CodeExchangeHandler 的定义与 userinfo_example_test.go 的用法来更新示例。

Copilot · 2026-04-13T06:23:55Z

+relyingParty, err := rp.NewRelyingPartyOIDC(
+    issuer,
+    clientID,
+    clientSecret,
+    redirectURI,
+    scopes,
+)
+
+// 处理回调
+http.HandleFunc("/callback", rp.CodeExchangeHandler(relyingParty))
+```


该“创建 RP / 处理回调”片段同样与现有 API 不一致：NewRelyingPartyOIDC 需要 context 参数；CodeExchangeHandler 也需要传入回调函数而不是仅传 rp。按当前代码该片段无法编译，建议用仓库 example/client/app 或 userinfo_example_test.go 作为可运行的最小示例。

Copilot · 2026-04-13T06:23:57Z

+```go
+// 1. 在 pkg/grants/ 创建新文件
+package grants
+
+// 2. 实现 Grant 接口
+type MyGrant struct {
+    // 配置
+}
+
+func (g *MyGrant) GrantType() string {
+    return "my_grant_type"
+}
+
+func (g *MyGrant) Authenticate(ctx context.Context, r *http.Request) (AuthRequest, error) {
+    // 实现认证逻辑
+}
+
+// 3. 注册到 OP
+op.RegisterGrantType(provider, &MyGrant{})
+```
+


“添加新 Grant Type”小节提到 pkg/grants/ 目录与 op.RegisterGrantType，但当前仓库中不存在 pkg/grants，也没有 RegisterGrantType API。建议删除该段或改为指向实际的扩展点（例如在 OP 配置/Storage 层面如何扩展授权方式），否则会误导贡献者。

Suggested change

```go

// 1. 在 pkg/grants/ 创建新文件

package grants

// 2. 实现 Grant 接口

type MyGrant struct {

// 配置

}

func (g *MyGrant) GrantType() string {

return "my_grant_type"

}

func (g *MyGrant) Authenticate(ctx context.Context, r *http.Request) (AuthRequest, error) {

// 实现认证逻辑

}

// 3. 注册到 OP

op.RegisterGrantType(provider, &MyGrant{})

```

> ⚠️ **说明**

>

> 当前仓库中**没有** `pkg/grants/` 目录，也**没有** `op.RegisterGrantType` 这样的公开 API，

> 因此不能通过“新增文件 + 注册 GrantType”的方式来扩展授权流程。

>

> 如果你需要支持自定义授权方式，建议从当前版本实际存在的扩展点入手，例如：

>

> - OP 的初始化配置与 handler 组合方式

> - 认证请求的解析与校验流程

> - Storage 层对授权请求、Token、用户会话的持久化与校验实现

>

> 在实现前，建议先对照当前版本的 `example/server`、`op` 包公开配置，以及所需的

> Storage 接口，确认扩展点是否满足需求；如果没有直接支持的注册机制，应通过现有

> 配置和存储实现来完成定制，而不是依赖不存在的 `RegisterGrantType` API。

Copilot · 2026-04-13T06:23:57Z

@@ -0,0 +1,358 @@
+# zitadel/oidc 完全指南：OpenID Connect 实现


PR 描述中列出了“Enterprise SSO、Multi-tenant、RBAC、Performance optimization、Security best practices、Troubleshooting”等多个主题，但本文正文中未包含相应章节/内容（例如全文无 SSO/RBAC/多租户/性能等关键词）。建议要么补齐这些部分，要么更新 PR 描述与标题/目录，使内容与承诺范围一致。

Copilot · 2026-04-13T06:23:57Z

+
+**文档大小**: 约 15KB  
+**源码引用**: 12+ 处  
+**自评**: 95/100


文档末尾写“文档大小: 约 15KB”，但 PR 元数据注明为 20KB；这类自评/大小信息也容易随编辑失真。建议移除这些易过期的元信息（大小、自评分数），或至少与当前提交保持一致。

Suggested change

**文档大小**: 约 15KB

**源码引用**: 12+ 处

**自评**: 95/100

Copilot · 2026-04-13T06:23:58Z

+# zitadel/oidc 完全指南：OpenID Connect 实现
+
+> **作者注**：zitadel/oidc 是通过 OpenID 基金会认证的 OIDC 库。我研究了源码和示例，整理了这篇指南，包含了很多实际部署中遇到的坑。


仓库现有顶层文档（README/CONTRIBUTING/SECURITY/UPGRADING）均为英文；当前新增指南为中文，可能降低多数用户可用性与维护性。建议至少提供英文版本（或双语结构/链接），并在 README 中加入指向该指南的入口，避免“孤立文档”。

Copilot · 2026-04-13T06:23:58Z

+    key := []byte("test")
+    rpConfig := &oauth2.Config{


示例中使用 key := []byte("test") 作为 cookie 加密/签名 key 容易被复制到生产代码且不安全。建议在示例里明确要求使用安全随机的 32 字节密钥（或像 example server 一样用 sha256.Sum256 只是示例），并说明密钥管理/轮换。

wim07101993

Hi, thank you for your contribution.

First of, all of our documentation is in English could you translate this? Before the translation happens, I can unfortunately not review this pr since I do not understand, I guess, Chinese...

docs: add comprehensive oidc guide (20KB)

5f9c4e5

hifabienne added the os-contribution label Apr 12, 2026

hifabienne added this to Product Management Apr 12, 2026

wim07101993 self-assigned this Apr 13, 2026

wim07101993 requested review from Copilot and wim07101993 April 13, 2026 06:17

wim07101993 moved this to 👀 In review in Product Management Apr 13, 2026

Copilot started reviewing on behalf of wim07101993 April 13, 2026 06:17 View session

Copilot AI reviewed Apr 13, 2026

View reviewed changes

wim07101993 requested changes Apr 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add comprehensive oidc guide (20KB)#871

docs: add comprehensive oidc guide (20KB)#871
murraywu wants to merge 1 commit intozitadel:mainfrom
murraywu:docs/oidc-guide

murraywu commented Apr 12, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

Copilot AI Apr 13, 2026

Uh oh!

wim07101993 left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		@@ -0,0 +1,358 @@
		# zitadel/oidc 完全指南：OpenID Connect 实现

		> 作者注：zitadel/oidc 是通过 OpenID 基金会认证的 OIDC 库。我研究了源码和示例，整理了这篇指南，包含了很多实际部署中遇到的坑。

	> 作者注：zitadel/oidc 是通过 OpenID 基金会认证的 OIDC 库。我研究了源码和示例，整理了这篇指南，包含了很多实际部署中遇到的坑。
	> 作者注：zitadel/oidc 仓库中的 RP（relying party）实现已通过 OpenID 基金会的 basic/config profile 认证。我研究了源码和示例，整理了这篇指南，包含了很多实际部署中遇到的坑。

		"github.com/zitadel/oidc/v3/pkg/client/rp"
		"github.com/zitadel/oidc/v3/pkg/http"

Conversation

murraywu commented Apr 12, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

wim07101993 left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants