[proposal] Yggdrasil Oauth Specification

[pingguomc]

[提案] Yggdrasil Oauth 规范

经过对 Yggdrasil Connect 提案 #268 未获通过经验的总结，结合当下 Minecraft 玩家的实际需求，我决定重新发起提案。

Important

本提案并不要求强制实施。

概述

LittleSkin | 通过 OAuth 访问 Yggdrasil API 已经规定了大部分内容，此处直接引用。

所谓 Oauth 规范，实际上是对 Yggdrasil 登录 API 的更改，其他部分 API 保持不变。

更改的内容主要用于取代 Yggdrasil服务端规范 | 登录 API。
大体上就是换了个方式获得 accessToken，来增强安全性、可管理性和便捷性。
因此，对于原有的其他 API 对接较为简易。

---

下面是 Oauth 2.0 基本流程。

（A）客户端（Client）向资源所有者（Resource Owner）请求资源授权。授权请求可以直接向资源所有者（Resource Owner）发起，不过最好是通过授权服务器（Authorization Server）间接发起。
（B) 客户端（Client）得到资源所有者（Resoure Owner）的授权，这通常是一个凭据；授权的形式和凭据可以有不同的类型。RFC 6749 定义了四种主要的授权类型（下文进一步介绍）
（C）客户端（Client）向授权服务器（Authorization Server）出示授权（来自Resource Owenr的）凭据进行身份认证；并申请用于访问资源授权的访问令牌（Access Token）
（D) 授权服务器（Authorization Server）对客户端（Client）进行身份验证并验证授权授予，如果通过验证，则颁发访问令牌（Access Token）。
（E）客户端（Client）通过向资源服务器（Resource Server）发起令牌（Access Token）验证，请求被保护的资源。
（F）资源服务器（Resource Server)验证访问令牌（Access Token）；如果通过认证，则返回请求的资源。
—— 深入理解OAuth 2.0：原理、流程与实践

---

这里有两种情况，一是 启动器 作为 客户端 行驶流程，二是 Yggdrasil服务端 并不保存用户数据，而是通过第三方（如微软）来登录。

对于第一种情况，要求 启动器 和 Yggdrasil服务端 完成所有部分的代码，建议参考 LittleSkin | 通过 OAuth 访问 Yggdrasil API 来制定规范。

对于第二种情况，由于鉴权登录等流程均由 Yggdrasil服务端 执行，因此启动器只需要提供直接填写 accessToken 的登录方式即可。

我个人认为这两种情况的规范可以一同制定，以便各位开发者选择。

附言

我个人认为，可以选择重启 #268 ，并将我的提案作为副本关闭，或者根据我的提案进行更改并实施。

Important

这只是一个提案/建议，不包括具体的实现方案。更具体的内容将发布在评论的第一个隐藏内容。

1. 启动器 自行选择是否实现，并且我建议保留原有的身份验证机制，让用户选择。
2. Yggdrasil服务端 自行选择是否实现，但我不建议开发者继续开发和维护原有的身份验证机制。
3. Minecraft服务端 无需更改。

---

必要性

authlib-injector 外置登录利用了 Minecraft 自带的 Yggdrasil 鉴权认证系统，已经成为了多人游戏中用户身份认证的主流手段之一。

但传统的 Yggdrasil API 仍然存在设计上的缺陷。Yggdrasil API 的 登录 API 需要由启动器直接处理用户输入的账号和密码，并将其在 HTTP 请求中明文发送，这给了恶意程序盗取用户机密信息的可乘之机；且该 API 在设计上几乎没有考虑到二步验证，无法良好地保障用户的资产安全。

为解决这一问题，Mojang 在 2020 年 10 月宣布，将原先的 Mojang 账号体系迁移至 Microsoft 账号，以在全平台上提供统一的身份认证体验，并通过 Microsoft 账号体系提供的多因素认证功能保障用户账号安全。这一迁移行动已于 2023 年 12 月完成。

那，第三方 Yggdrasil 认证服务器呢？

作为事实上的国内最大第三方 Yggdrasil 验证服务器，长期以来，LittleSkin 饱受不同启动器上身份认证体验不统一导致的用户体验低下的问题的折磨（一个典型的例子是 PCL，其在登录失败时不会向用户展示验证服务器返回的错误详情，而是显示一个其推测的所有可能原因的文字模板，这一问题直至 PCL 2.8.6 才得以解决）；也因为传统 Yggdrasil API 的登录 API 不支持「直接输入用户名和密码」以外的身份认证方式，LittleSkin 一直无法实装用户体验良好的二步验证和社交网站登录功能。

——LittleSkin 用户使用手册

事实上， Oauth 已经被实现并使用，而没有规范几乎必定会导致 服务端、启动器 之间 不通用、不适配的问题出现。

[pingguomc]

Important

以下内容仅供参考，并不作为最终规范。

1. 概述

本规范为Minecraft Yggdrasil认证系统定义OAuth 2.0扩展，旨在替代原有的登录API，增强安全性、可管理性和用户体验。

2. 授权流程

2.1 授权码模式 + PKCE（推荐）

个人建议使用该流程。

本流程图使用 AI 生成

sequenceDiagram
    participant C as 客户端(启动器)
    participant B as 浏览器
    participant AS as 授权服务器
    participant RS as 资源服务器(Yggdrasil)

    Note over C,RS: 初始化阶段
    C->>C: 生成code_verifier和code_challenge
    
    Note over C,RS: 授权请求
    C->>B: 1. 打开授权URL<br/>包含code_challenge
    B->>AS: 2. 用户认证和授权
    AS->>B: 3. 返回授权码<br/>(redirect_uri?code=xxx)
    B->>C: 4. 传递授权码
    
    Note over C,RS: 令牌交换
    C->>RS: 5. 请求访问令牌<br/>(授权码 + code_verifier)
    RS->>AS: 6. 验证授权码和PKCE
    AS->>RS: 7. 返回访问令牌
    RS->>C: 8. 返回accessToken和profile
    
    Note over C,RS: 资源访问
    C->>RS: 9. 使用accessToken访问API
    RS->>C: 10. 返回请求的资源

Loading

2.2 第三方集成模式（简化流程）

对于Yggdrasil服务端通过第三方（如微软）登录的情况(待定)：

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "third_party",
  "provider": "microsoft",
  "access_token": "第三方访问令牌",
  "client_id": "可选客户端标识"
}

3. 实现

参考 little skin

4. 安全要求

1. PKCE要求：所有客户端应该实现PKCE（RFC 7636）
2. State参数：所有授权请求应包含cryptographically random state参数
3. HTTPS要求：生产环境必须使用HTTPS
4. 令牌存储：客户端须安全存储访问令牌和刷新令牌
5. 重定向URI验证：服务端必须验证重定向URI

5. 错误处理

与原有的格式保持一致

[RyogiMutsuki]

RFC 6749 已经是规范了

现在不通用的原因要不然是启动器实现中硬编码了 Microsoft Entra ID 的 Token 端点，要不然就是 Yggdrasil Connect 中对于 Client Id 没有绝对稳定的获取方式，导致压根没 Client Id 可以用

[tnqzh123]

对于第二种情况，由于鉴权登录等流程均由 Yggdrasil服务端 执行，因此启动器只需要提供直接填写 accessToken 的登录方式即可。

2.2 第三方集成模式（简化流程）

对于Yggdrasil服务端通过第三方（如微软）登录的情况(待定)：

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "third_party",
  "provider": "microsoft",
  "access_token": "第三方访问令牌",
  "client_id": "可选客户端标识"
}

你是认真的吗？要把一个可能含有敏感 scope 的 OAuth Access Token 暴露给一个完全不由你控制的第三方？

我整篇通读下来几乎完全不理解你设计的规范是什么样的，我完全不知道客户端要怎么发送请求、服务端要怎么处理客户端发来的请求、服务端怎么返回响应、客户端怎么处理服务端返回的响应。硬要说的话，我只感觉到你这个提案只是在理念上提取了 OAuth 的糟粕（比现有方案更繁琐的授权流程），而完全舍弃了 OAuth 的精华（精细化的权限管理、令牌生命周期、高度可自定义的认证流程 etc.）。

你真的理解 OAuth 吗？作为规范的设计者，你真的有完整地阅读并理解了你设计的规范依赖的底层协议的规范吗？或者说，咱能不能少用点生成式 AI，多动动自己聪明的小脑瓜呢？

我也不建议直接拿 LittleSkin 用户使用手册里的那套基于 OAuth、把 Minecraft Token 作为一种资源（resource）的方案来改，因为那一套不管是客户端实现还是服务端实现都要比基于 OpenID Connect 的方案（也就是 Yggdrasil Connect）更复杂，而且同样几乎只取糟粕舍弃精华，否则我就直接推那一套了，也不会重新写一个 Yggdrasil Connect。

[tnqzh123]

@copytiao

要不然就是 Yggdrasil Connect 中对于 Client Id 没有绝对稳定的获取方式，导致压根没 Client Id 可以用

对于这种情况，我的建议是视为该验证服务器不支持 Yggdrasil Connect，回退到传统 Auth Server。

如果一个验证服务器既没有提供公用应用 ID、也不支持应用动态注册、传统 Auth Server 也不让用，说明这个验证服务器根本就不接受没有主动注册的启动器。这是验证服务器的问题，不是启动器的问题。理想情况下（也应该这样做），认证服务器此时应该在传统 Auth Server 返回的错误的 errorMessage 中说明应该使用何种方式登录。

当然，如果启动器愿意的话，也可以在高级选项里提供一个手动填写 Client ID 的地方。

[pingguomc]

@tnqzh123

对于第二种情况，由于鉴权登录等流程均由 Yggdrasil服务端 执行，因此启动器只需要提供直接填写 accessToken 的登录方式即可。

2.2 第三方集成模式（简化流程）

对于Yggdrasil服务端通过第三方（如微软）登录的情况(待定)：
POST /oauth/token
Content-Type: application/json

{
"grant_type": "third_party",
"provider": "microsoft",
"access_token": "第三方访问令牌",
"client_id": "可选客户端标识"
}

你是认真的吗？要把一个可能含有敏感 scope 的 OAuth Access Token 暴露给一个完全不由你控制的第三方？

我整篇通读下来几乎完全不理解你设计的规范是什么样的，我完全不知道客户端要怎么发送请求、服务端要怎么处理客户端发来的请求、服务端怎么返回响应、客户端怎么处理服务端返回的响应。硬要说的话，我只感觉到你这个提案只是在理念上提取了 OAuth 的糟粕（比现有方案更繁琐的授权流程），而完全舍弃了 OAuth 的精华（精细化的权限管理、令牌生命周期、高度可自定义的认证流程 etc.）。

你真的理解 OAuth 吗？作为规范的设计者，你真的有完整地阅读并理解了你设计的规范依赖的底层协议的规范吗？或者说，咱能不能少用点生成式 AI，多动动自己聪明的小脑瓜呢？

我也不建议直接拿 LittleSkin 用户使用手册里的那套基于 OAuth、把 Minecraft Token 作为一种资源（resource）的方案来改，因为那一套不管是客户端实现还是服务端实现都要比基于 OpenID Connect 的方案（也就是 Yggdrasil Connect）更复杂，而且同样几乎只取糟粕舍弃精华，否则我就直接推那一套了，也不会重新写一个 Yggdrasil Connect。

对于您提出的批评，我接受。
我提出的样例是极其危险的，我考虑不周。

但是我本意不是由我自己提出一个完整规范并让大家进行审查。我的意思是我们需要，但是我个人做不到制定一个规范，所以我向社区提出。

文是我自己写的，只有 流程图 是AI生成的。

你的判断是正确的，我只是学习和了解过 Oauth，并没有自行开发过 Oauth 程序，但是我深受不规范导致的困扰。我找不到有能力的人来帮助我提出或者解决这个问题，我只能自己提出。

如果您能重新提出规范，我愿意将我的 Issues 作为您的副本关闭。

[pingguomc]

现在看起来现在这个 Issue 已经无用了。

[melamit]

@pingguomc Sounds like slop

[pingguomc]

@pingguomc Sounds like slop

What do you mean

[melamit]

@pingguomc I didn't know bot mirrors replies from telegram, I was talking about the initial idea from adding external auth support

[pingguomc]

@pingguomc I didn't know bot mirrors replies from telegram, I was talking about the initial idea from adding external auth support

What？I can't understand.

[melamit]

@pingguomc i am replying using the bot in the authlib-injector telegram channel

[pingguomc]

I seem to understand. I didn't know I had the authlib-injector telegram before.
So, what do you want to say?

[melamit]

@pingguomc well, you can check out this one https://t.me/authlib_injector, it doesn't seem to be official i guess, but i thought only people in the chat itself will see that

[pingguomc]

@pingguomc well, you can check out this one https://t.me/authlib_injector, it doesn't seem to be official i guess, but i thought only people in the chat itself will see that

No, I said you said "Sounds like slop". I CANNOT understand that.