Skip to content

docs(auth): define unified identity federation architecture #630

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
XiaoSeS wants to merge 3 commits into
base: main
Choose a base branch
from
+2,589 −9
Open

docs(auth): define unified identity federation architecture #630

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a4f0649
docs(auth): define unified identity federation architecture
XiaoSeS Jul 30, 2026
21ac74f
docs(auth): consolidate identity delivery tracking
Aug 5, 2026
c145d14
docs(auth): clarify staged PR workflow
Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/03-authentication-design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
# skillhub 认证与授权设计

> 外部身份架构说明：LDAP、DingTalk、CAS、SAML、可信代理及其他新外部身份接入，
> 以 [统一身份联邦设计](./21-unified-identity-federation-design.md) 为准。本文现有
> `OAuthClaims`、`DirectAuthProvider` 和 `PassiveSessionAuthenticator` 接口描述的是
> 当前兼容实现，不是新 Provider 的目标扩展契约；新 Provider 只能返回协议验证结果，
> 由统一核心归一化为 `IdentityAssertion`，不得直接返回 `PlatformPrincipal`。

## 0. 身份标识约束

- `PlatformPrincipal.userId` 必须是稳定的字符串标识，而不是 `Long`。
Expand Down
9 changes: 8 additions & 1 deletion docs/11-auth-extensibility-and-private-sso.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# 认证扩展与私有 SSO 兼容设计

> 状态说明：本文记录当前 Direct/Passive 私有 SSO 兼容入口。新外部身份实现和这些入口的
> 后续迁移，以 [统一身份联邦设计](./21-unified-identity-federation-design.md) 为准。
> `DirectAuthProvider` 和 `PassiveSessionAuthenticator` 直接返回
> `PlatformPrincipal` 的方式属于待迁移设计，不应继续扩展到 LDAP、CAS、DingTalk、
> SAML 或新的私有 SSO。新 Adapter 只返回协议验证结果，由统一核心归一化为
> `IdentityAssertion`。

## 1. 目标

在不影响当前开源版 OAuth 和本地账号登录能力的前提下，为未来私有仓库接入企业 SSO 预留稳定扩展点，并把代码差异控制在 provider 实现层和少量配置层。
Expand Down Expand Up @@ -145,4 +152,4 @@ public interface DirectAuthProvider {

更详细的私有 SSO 接入步骤、最佳实践、测试矩阵和给后续 coding agent 的执行约束，见：

- [12-private-sso-integration-playbook.md](/Users/xudongsun/github/skillhub/docs/12-private-sso-integration-playbook.md)
- [12-private-sso-integration-playbook.md](./12-private-sso-integration-playbook.md)
21 changes: 13 additions & 8 deletions docs/12-private-sso-integration-playbook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# 私有 SSO 接入兼容层实施手册

> 状态说明：本文是现有私有 SSO 兼容入口的历史实施手册。新接入应先遵循
> [统一身份联邦设计](./21-unified-identity-federation-design.md)，由 Provider 返回协议
> 验证结果，再由统一核心归一化为 `IdentityAssertion`；不得直接构造
> `PlatformPrincipal`。本文中相反的代码示例只用于理解当前兼容实现。

## 1. 文档目的

本文档面向两类读者：
Expand All @@ -11,10 +16,10 @@

相关文档：

- [03-authentication-design.md](/Users/xudongsun/github/skillhub/docs/03-authentication-design.md)
- [06-api-design.md](/Users/xudongsun/github/skillhub/docs/06-api-design.md)
- [08-frontend-architecture.md](/Users/xudongsun/github/skillhub/docs/08-frontend-architecture.md)
- [11-auth-extensibility-and-private-sso.md](/Users/xudongsun/github/skillhub/docs/11-auth-extensibility-and-private-sso.md)
- [03-authentication-design.md](./03-authentication-design.md)
- [06-api-design.md](./06-api-design.md)
- [08-frontend-architecture.md](./08-frontend-architecture.md)
- [11-auth-extensibility-and-private-sso.md](./11-auth-extensibility-and-private-sso.md)

## 2. 当前上下文与已确认约束

Expand Down Expand Up @@ -54,9 +59,9 @@

关键代码位置：

- [DirectAuthProvider.java](/Users/xudongsun/github/skillhub/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/direct/DirectAuthProvider.java)
- [PassiveSessionAuthenticator.java](/Users/xudongsun/github/skillhub/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/bootstrap/PassiveSessionAuthenticator.java)
- [PlatformSessionService.java](/Users/xudongsun/github/skillhub/server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/session/PlatformSessionService.java)
- [DirectAuthProvider.java](../server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/direct/DirectAuthProvider.java)
- [PassiveSessionAuthenticator.java](../server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/bootstrap/PassiveSessionAuthenticator.java)
- [PlatformSessionService.java](../server/skillhub-auth/src/main/java/com/iflytek/skillhub/auth/session/PlatformSessionService.java)

### 3.2 后端公共协议

Expand Down Expand Up @@ -415,7 +420,7 @@ skillhub:

如果后续由 AI 继续在私有仓库上完成接入，建议严格遵守以下执行规则：

- 先读 [11-auth-extensibility-and-private-sso.md](/Users/xudongsun/github/skillhub/docs/11-auth-extensibility-and-private-sso.md) 和本文档
- 先读 [11-auth-extensibility-and-private-sso.md](./11-auth-extensibility-and-private-sso.md) 和本文档
- 不要重构现有公共认证主链路，除非发现明确 bug
- 私有 SSO 的具体实现优先写成 provider、authenticator、client、identity service
- 不要复制 `PlatformSessionService` 逻辑
Expand Down
Loading
Loading