Skip to content

Commit 88c0e65

Browse files
tnqzh123SerinaNyaXieXiLin2
authored
feat(oauth,api): Device Authorization Grant & OAuth for Yggdrasil API
* refactor(oauth,api): rewrite & rearrangement * ✏️ typo(advanced/api.md): fix typo * ⚡️ perf(oauth2/authorization-code-grant): optimized * ✨ feat(oauth2/device-authorization-grant): init file * feat(oauth2/device-authorization-grant): add doc content * perf(api): apply suggestions * perf(oauth/authorization-code-grant): remove unnecessary formatting * pref(oauth/index): change chapter title: 请求用户授权 -> 获取访问令牌 * fix(oauth/device-authorization-grant): fix typo * refactor(api): update * refactor(oauth): move 刷新访问令牌 to authorization-code-grant from index Yggdralt doesn't support access token refresh currently. * feat(oauth,api): add note to add Accept header in oauth index and api docs * feat(oauth): add description for error response when access token or scope is invalid * fix(oauth): fix link to LittleSkin API * feat(api): add APIs for Yggdrasil * feat(oauth): add info about player selection when authorize and ID Token * feat(feature): oauth-for-yggdrasil * fix(oauth/device-authorize-grant): fix link for contact for whitelist * perf(oauth): set outline level * fix(oauth/device-authorization-grant): remove refresh token in token response Yggdralt doesn't support access token refresh currently. * feat(oauth/device-authorization-grant): add note for refresh token is not supported Yggdralt doesn't support access token refresh currently. * ⚡ pref(advanced/api): add ref name * 🐛 fix(feature/oauth-for-yggdrasil): two urls * ⚡️ perf(oauth): optimized a lot * Apply suggestions from code review Co-authored-by: Steven Qiu <[email protected]> * format(oauth-for-yggdrasil): remove line break * fix(api): fix api endpoint * feat(device-authorization-grant): require openid permission to get ID Token * feat(device-authorization-grant): Yggdrasil permissions now require whitelists * feat(device-authorization-grant): add contact info * feat(api): update descriptions * ✨ feat(openapi): add 2 APIs - Get all Yggdrasil Profiles - Create Minecraft token * feat(device-authorization-grant): add tip for JWT sig alg --------- Co-authored-by: SerinaNya <[email protected]> Co-authored-by: XieXiLin <[email protected]>
1 parent aba0fe6 commit 88c0e65

File tree

9 files changed

+800
-243
lines changed

9 files changed

+800
-243
lines changed

‎docs/.vitepress/config.mts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,7 @@ export default defineConfig({
172172
link: '/feature/',
173173
items: [
174174
{ text: 'Passkey 登录', link: '/feature/passkey-login' },
175+
{ text: 'OAuth for Yggdrasil', link: '/feature/oauth-for-yggdrasil' },
175176
]
176177
}
177178
]
@@ -202,7 +203,14 @@ export default defineConfig({
202203
text: '高级功能',
203204
link: '/advanced/',
204205
items: [
205-
{ text: 'OAuth 2', link: '/advanced/oauth2' },
206+
{
207+
text: 'OAuth 2',
208+
link: '/advanced/oauth2',
209+
items: [
210+
{ text: '授权代码流', link: '/advanced/oauth2/authorization-code-grant' },
211+
{ text: '设备代码流', link: '/advanced/oauth2/device-authorization-grant' },
212+
]
213+
},
206214
{ text: 'LittleSkin API', link: '/advanced/api' },
207215
]
208216
},

‎docs/advanced/api.md‎

Lines changed: 147 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -7,19 +7,31 @@ outline: [2, 3]
77
<!--@include: ./for-experts.template.md-->
88

99
::: warning 注意
10-
当前 Blessing Skin Server API 和我们的部分 API 正处于试验阶段，API 不稳定并随时可能发生破坏性变更，敬请留意。
10+
当前 Blessing Skin API 和我们的部分 API 正处于试验阶段，API 不稳定并随时可能发生破坏性变更，敬请留意。
1111
:::
1212

13-
LittleSkin 使用 Blessing Skin 最新开发版本，支持通过 Blessing Skin Server API 使用 LittleSkin 的各种功能，包括但不限于获取角色信息、更改角色材质等。
13+
LittleSkin 使用 Blessing Skin 最新开发版本，支持通过 Blessing Skin API 使用 LittleSkin 的各种功能，包括但不限于获取角色信息、更改角色材质等。
1414

15-
除此之外，LittleSkin 有一些定制的 API，这些通常是 Blessing Skin Server API 不具备的。
15+
除此之外，LittleSkin 有一些原版 Blessing Skin API 不具备的定制 API。
1616

17-
通常来说，此页面列出的大多数 API 均需鉴权。一些无需鉴权即可使用的 API 会被特别标出。
17+
通常来说，此页面列出的大多数 API 均需 [鉴权](./oauth2/index.md#使用访问令牌进行鉴权)。一些无需鉴权即可使用的 API 会被特别标出。
1818

19-
## Blessing Skin Server API 文档
19+
---
20+
21+
[[toc]]
22+
23+
## Blessing Skin API 文档
24+
25+
按理来说，LittleSkin 的 Blessing Skin API 与原版 Blessing Skin API 完全一致，你可以直接参考 Blessing Skin API 的文档：[Blessing Skin 用户手册 - Web API](https://blessing.netlify.app/api/)。
26+
27+
除此之外，这里还有一些 Blessing Skin API 的文档中没有提到的，请求部分 API 时可能需要请求用户授予的权限：
2028

21-
按理来说，LittleSkin 的 Blessing Skin Server API 与原版 Blessing Skin Server API 完全一致，
22-
你可以直接参考 Blessing Skin Server API 的文档：[Blessing Skin 用户手册 - Web API](https://blessing.netlify.app/api/)
29+
| 权限节点 | 解释 |
30+
| ---------------------------------- | ----------------------------- |
31+
| `User.Read` | 读取用户基本信息 |
32+
| `Player.Read` / `Player.ReadWrite` | 读取 / 读写用户的角色和对应材质 |
33+
| `Closet.Read` / `Closet.ReadWrite` | 读取 / 读写用户的衣柜收藏 |
34+
| `Notification.Read` | 读取用户的站内通知 |
2335

2436
## LittleSkin 特有的 API
2537

@@ -30,32 +42,25 @@ LittleSkin 使用 Blessing Skin 最新开发版本，支持通过 Blessing Skin
3042
若 OpenAPI 文档中的表述与此文档不一致，以 OpenAPI 文档为准。
3143
</NCard>
3244

33-
### 站点公告 Announcements <Badge type="info" text="🔓 无需鉴权" />
45+
### 站点公告 Announcements <Badge type="info" text="🔓 无需鉴权" /> {#get-announcements}
3446

3547
```http
36-
GET https://littleskin.cn/api/announcements
48+
GET https://littleskin.cn/api/announcements HTTP/1.1
49+
Accept: application/json
3750
```
3851

3952
返回站点公告的列表。
4053

4154
未来将遵守启动器联盟规范。<Badge type="info" text="不成熟的" />
4255

43-
::: details 说明
56+
::: details 响应说明
4457

4558
以下只是对 OpenAPI 文档的额外补充说明。
4659

47-
| 值 | 简要解释 |
48-
| ----------- | ----------------------------------------------- |
49-
| `title` | 同 `content`，但通常只是纯文本 |
50-
| `content` | 可能会包含一些简单的 HTML 标签，如 `<p>` `<ul>` |
51-
| `color` | 颜色名称取自 Bootstrap UI |
52-
| `priority` | 值越大，优先级越高，应被安排在上方或前方展示 |
53-
| `severity` | 公告的重要/严重性 |
54-
| `expand` | 对于 `<details>` 标签，若为 `false` 则默认收起 |
55-
| `timestamp` | Unix 时间戳，单位为秒 |
56-
| `id` | UUID v4，对公告进行了修改不会改变 |
60+
```http
61+
HTTP/1.1 200 OK
62+
Content-Type: application/json
5763
58-
```json
5964
[
6065
{
6166
"title": "string",
@@ -70,34 +75,147 @@ GET https://littleskin.cn/api/announcements
7075
]
7176
```
7277

78+
| 值 | 简要解释 |
79+
| ----------- | ----------------------------------------------- |
80+
| `title` | 同 `content`，但通常只是纯文本 |
81+
| `content` | 可能会包含一些简单的 HTML 标签，如 `<p>` `<ul>` |
82+
| `color` | 颜色名称取自 Bootstrap UI |
83+
| `priority` | 值越大，优先级越高，应被安排在上方或前方展示 |
84+
| `severity` | 公告的重要/严重性 |
85+
| `expand` | 对于 `<details>` 标签，若为 `false` 则默认收起 |
86+
| `timestamp` | Unix 时间戳，单位为秒 |
87+
| `id` | UUID v4，对公告进行了修改不会改变 |
88+
7389
:::
7490

75-
### 查询正版验证状态 PremiumVerification <Badge type="tip" text="🔒 需要鉴权" />
91+
### 查询正版验证状态 PremiumVerification <Badge type="tip" text="🔒 需要鉴权" /> {#premiun-verification}
7692

7793
```http
78-
GET https://littleskin.cn/api/premium-verification
94+
GET https://littleskin.cn/api/premium-verification HTTP/1.1
95+
Accept: application/json
7996
```
8097

8198
返回用户正版验证状态。
8299

83-
需要在 [OAuth2](./oauth2.md) 阶段提供 `PremiumVerification.Read` Scope。
100+
需要在 [OAuth 2 授权](./oauth2/index.md#获取访问令牌) 时请求 `PremiumVerification.Read` 权限。
84101

85-
::: details 说明
102+
::: details 响应说明
86103

87104
以下只是对 OpenAPI 文档的额外补充说明。
88105

106+
```http
107+
HTTP/1.1 200 OK
108+
Content-Type: application/json
109+
110+
{
111+
"code": 0,
112+
"verified": true,
113+
"uuid": "69e535e98159409e93c8d649d7355279"
114+
}
115+
```
116+
89117
| 值 | 简要解释 |
90118
| ---------- | ------------------------------- |
91119
| `code` | 状态码，目前只有 `0` |
92120
| `verified` | 是否已验证正版 |
93121
| `uuid` | 无符号的正版 UUID，当存在时返回 |
94122

95-
```json
123+
:::
124+
125+
### <Badge type="tip" text="Yggdrasil" /> 获取用户名下所有角色的 Yggdrasil 档案 <Badge type="tip" text="🔒 需要鉴权" /> {#get-all-yggdrail-profiles-of-user}
126+
127+
```http
128+
GET https://littleskin.cn/api/yggdrasil/sessionserver/session/minecraft/profiles HTTP/1.1
129+
Accept: application/json
130+
```
131+
132+
返回用户名下所有角色的 Yggdrasil 档案。
133+
134+
需要在 [OAuth 2 授权](./oauth2/index.md#获取访问令牌) 时请求 `Yggdrasil.PlayerProfiles.Read` 权限。
135+
136+
::: details 响应说明
137+
138+
以下只是对 OpenAPI 文档的额外补充说明。
139+
140+
```http
141+
HTTP/1.1 200 OK
142+
Content-Type: application/json
143+
144+
[
145+
{
146+
"id": "{{uuid}}",
147+
"name": "{{name}}",
148+
"properties": [
149+
{
150+
"name": "{{property_name}}",
151+
"value": "{{property_value}}"
152+
}
153+
]
154+
}
155+
]
156+
```
157+
158+
| 参数 | 类型 | 值 |
159+
| -------------------- | ------ | ------------------------------------------------------------ |
160+
| （最外层的数组自身） | array | 用户名下的所有角色列表 |
161+
| `[]`（数组元素） | object | Yggdrasil 档案（不包含签名），详见 [Yggdrasil 服务端技术规范 - 角色信息的序列化](https://github.com/yushijinhun/authlib-injector/wiki/Yggdrasil-%E6%9C%8D%E5%8A%A1%E7%AB%AF%E6%8A%80%E6%9C%AF%E8%A7%84%E8%8C%83#%E8%A7%92%E8%89%B2%E4%BF%A1%E6%81%AF%E7%9A%84%E5%BA%8F%E5%88%97%E5%8C%96) |
162+
163+
:::
164+
165+
> [!TIP] 只需要获取已知角色的档案？
166+
> 在已知角色名或角色 UUID 的情况下，可直接通过请求 Yggdrasil API 获取角色的 Yggdrasil 档案，无需鉴权。请参阅：[Yggdrasil 服务端技术规范 - 角色部分](https://github.com/yushijinhun/authlib-injector/wiki/Yggdrasil-%E6%9C%8D%E5%8A%A1%E7%AB%AF%E6%8A%80%E6%9C%AF%E8%A7%84%E8%8C%83#%E8%A7%92%E8%89%B2%E9%83%A8%E5%88%86)
167+
168+
### <Badge type="tip" text="Yggdrasil" /> 获取 Minecraft 令牌 <Badge type="tip" text="🔒 需要鉴权" /> {#get-minecraft-token}
169+
170+
```http
171+
POST https://littleskin.cn/api/yggdrasil/authserver/oauth HTTP/1.1
172+
Accept: application/json
173+
Content-Type: application/json
174+
96175
{
97-
"code": 0,
98-
"verified": true,
99-
"uuid": "69e535e98159409e93c8d649d7355279"
176+
"uuid": "{{uuid}}"
100177
}
101178
```
102179

180+
获取一个用于访问 Yggdrasil API 的 Minecraft 令牌（即 Yggdrasil API 中的 Access Token）。
181+
182+
需要在 [OAuth 2 授权](./oauth2/index.md#获取访问令牌) 时请求 `Yggdrasil.MinecraftToken.Create` 权限。
183+
184+
| 参数 | 类型 | 值 |
185+
| -------------- | ------ | ------------------------------------- |
186+
| `uuid` | string | 选定的角色的 UUID，无符号 |
187+
188+
通过该 API 创建 Minecraft 令牌时不支持指定 Client Token，只能由服务端随机生成。
189+
190+
::: details 响应说明
191+
192+
以下只是对 OpenAPI 文档的额外补充说明。
193+
194+
```http
195+
HTTP/1.1 200 OK
196+
Content-Type: application/json
197+
198+
{
199+
"accessToken": "{{access_token}}",
200+
"clientToken": "{{client_token}}",
201+
"availableProfiles": [
202+
{
203+
"id": "{{uuid}}",
204+
"name": "{{name}}"
205+
}
206+
],
207+
"selectedProfile": {
208+
"id": "{{uuid}}",
209+
"name": "{{name}}"
210+
}
211+
}
212+
```
213+
214+
响应内容（包括错误响应）即是 Yggdrasil API 的登录 API 的响应内容，详见：[Yggdrasil 服务端技术规范 - 登录](https://github.com/yushijinhun/authlib-injector/wiki/Yggdrasil-%E6%9C%8D%E5%8A%A1%E7%AB%AF%E6%8A%80%E6%9C%AF%E8%A7%84%E8%8C%83#%E7%99%BB%E5%BD%95)
215+
216+
此 API 签发的 Minecraft 令牌与 Yggdrasil API 签发的 Minecraft 令牌一致，可直接通过 Yggdrasil API 进行刷新、验证、吊销、加入服务器等操作。同理，通过 Yggdrasil API 执行的登出操作也会使此 API 签发的 Minecraft 令牌被吊销。
217+
103218
:::
219+
220+
> [!TIP] Minecraft 令牌能用来做什么？
221+
> 请参阅 [Yggdrasil 外置登录](../yggdrasil/index.md)。

‎docs/advanced/for-experts.template.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
1-
::: tip 提示
2-
这篇文档是面向开发者的，普通用户可能无法理解。
3-
4-
如果你看不懂这个页面在说些什么，直接关闭这篇文档或者浏览其它文档即可，忽略这部分内容不会影响你正常使用 LittleSkin 的基础功能。
5-
:::
1+
> [!TIP] 🧑‍🔬 供开发者阅读的文章
2+
> 如果你看不懂这个页面在说些什么，直接关闭这篇文章或者浏览其它文章即可。
3+
>
4+
> 忽略此文章并不会影响你正常使用 LittleSkin 的基础功能。

0 commit comments

Comments
 (0)