User:Lzs/Authentication(Chinese)

Heads up! This page is out of date and kept as a historical reference. Contributions to update it are welcome.

(Is being translated into Chinese)

在Minecraft 1.6 中引入了一种名为 Yggdrasil 的新身份验证方案，完全取代了旧版认证系统。Mojang的其他游戏《Scrolls》也使用这种认证方式。 Mojang 表示 此身份验证系统应该被使用在每一个自定义登录上，但 绝不应从用户那里收集证书。

请求格式

所有请求是由以下服务器发往 Yggdrasil：

https://authserver.mojang.com

进一步说，他们预计将满足以下规则：

• 是 POST 请求
• Have the Content-Type header set to application/json
• Contain a JSON-encoded dictionary as payload

如果请求成功服务器将响应：

• 状态码 200
• A JSON-encoded dictionary according to the specifications below

If however a request fails, the server will respond with:

• An appropriate, non-200 HTTP status code
• 一个 JSON-编码字典格式如下:

{
    "error": "Short description of the error",
    "errorMessage": "Longer description which can be shown to the user",
    "cause": "Cause of the error" // 可选
}

错误

这些都是一些可能遇到的错误:

错误	原因	错误提示	注释
Method Not Allowed		请求中指定的方法是不允许的，因为资源标识来自URI请求。	收到POST请求以外的数据。
Not Found		服务器并没有发现任何匹配此请求的URI。	被呼叫的端点不存在。
ForbiddenOperationException	UserMigratedException	无效的证书。帐户迁移,使用电子邮件作为用户名。
ForbiddenOperationException		无效的证书。无效的用户名或密码。
ForbiddenOperationException		无效的证书。	此用户名近期尝试太多次登录(查看/authenticate)。注意，用户名和密码可能仍然是有效的！
ForbiddenOperationException		无效的令牌。	accessToken 是无效的。
IllegalArgumentException		访问令牌(Access token)已有一个指定的配置文件。	选择配置文件还未实现。
IllegalArgumentException		证书是空的。	用户名/密码未提交。
Unsupported Media Type		此服务器拒绝服务请求，因为实体请求的格式不受 请求的资源的请求的方法 支持。(翻译水平不足，无法理解请阅读英文原文)	数据未被应用程序提交/json

身份验证

使用他的密码对用户进行身份验证。

端点

/authenticate

有效载荷

{
    "agent": {                              // 默认为 Minecraft
        "name": "Minecraft",                // 适用于 Mojang 的其他游戏《Scrolls》， 应使用"Scrolls" 
        "version": 1                        // 这个数字可能会增加
                                            // 根据将来的客户端改变
    },
    "username": "mojang account name",      // 可以是一个电子邮件地址或玩家的名字
                                            // 对于迁移的帐户
    "password": "mojang account password",
    "clientToken": "client identifier",     // 可选
    "requestUser": true                     // 可选的，默认值：false；true将用户对象添加到响应中
}

此 clientToken 应该是一个随机生成的标识符并且对于每个请求必须是相同的。在首次运行启动器时生成一个随机的(版本4)UUID 并保存它，在后续请求中重复使用它。假如它丢失了，服务器将基于Java的 UUID.toString()生成一个随机的令牌并应被客户端储存。然而这也将使该用户的所有客户端先前获得的 accessToken 失效。

响应

{
    "accessToken": "random access token",      // 十六进制
    "clientToken": "client identifier",        // 与接收到的相同
    "availableProfiles": [                     // 只有当代理字段被接收时才存在
        {
            "id": "profile identifier",        // 十六进制
            "name": "player name",
            "legacy": true or false            // 实际上， 如果是true，这个字段只出现在响应中。默认为false.
        }
    ],
    "selectedProfile": {                       // 只有当代理字段被接收时才存在
        "id": "uuid without dashes",
        "name": "player name",
        "legacy": true or false
    },
    "user": {                                  // 只出现在请求有效载荷中requestUser为真时
        "id": "user identifier",               // 十六进制
        "properties": [
            {
                "name": "preferredLanguage",   // 可能不适用于所有帐户
                "value": "en"                  // 使用ISO 639-1标准，中文用zh表示
            },
            {
                "name": "twitch_access_token", // 只有当一个twitch 帐户被关联时才存在 (查看https://account.mojang.com/me/settings)
                "value": "twitch oauth token"  // OAuth 2.0 令牌; 字母数字混合; e.g. https://api.twitch.tv/kraken?oauth_token=[...]
                                               // 这里记录了Twitch的API: https://github.com/justintv/Twitch-API
            }
        ]
    }
}

注意： 如果用户希望呆在他们的电脑上登录，强烈建议将接收到的 accessToken 代替密码本身。

目前每个帐户只能拥有一个配置文件，不过在未来的计划中每个账户可以拥有多个配置文件。 如果用户没有附加Minecraft许可证的情况下试图登录到一个有效的Mojang账户，身份验证将会成功，但响应不会包含 selectedProfile 字段，并且 availableProfiles 数组将为空。

在某些情况下，观察到Mojang对遗留帐户的刷新尝试失败时返回一个null。目前还不清楚空响应的实际错误是什么并且非常罕见。但是，实现上应该警惕响应的空输出。

这个端点是频率限制;

多个 /authenticate 在很短的时间内对相同账户的请求 (在短时间内考虑 3 个请求)，即使有正确的密码， 最终将导致一个 Invalid credentials. 响应。这一错误在几秒钟后就会消失。

刷新

刷新一个有效的 accessToken。 它可以用来让用户在游戏会话之间登录并且优先在文件中存储用户的密码 (查看 lastlogin).

端点

/refresh

有效载荷

{
    "accessToken": "valid accessToken",
    "clientToken": "client identifier",  // 这需要与最初获得的accessToken相同
                                         //  
    "selectedProfile": {                 // 可选的；发送它将导致错误
        "id": "profile identifier",      // 十六进制
        "name": "player name"
    },
    "requestUser": true                  // 可选；默认值：false；true将用户对象添加到响应中
}

注意： 所提供的 accessToken 无效。

Response

{
    "accessToken": "random access token",      // 十六进制
    "clientToken": "client identifier",        // 与接收到的相同
    "selectedProfile": {
        "id": "profile identifier",            // 十六进制
        "name": "player name"
    },
    "user": {                                  // 只有在请求有效载荷中requestUser为true时才出现
        "id": "user identifier",               // 十六进制
        "properties": [
            {
                "name": "preferredLanguage",   // 可能不适用于所有帐户
                "value": "en"                  // ISO 639-1标准，中文使用zh表示
            },
            {
                "name": "twitch_access_token", // 只有在与twitch帐户相关联时会出现 (查看 https://account.mojang.com/me/settings)
                "value": "twitch oauth token"  // OAuth 2.0 令牌；字母数字混合；e.g. https://api.twitch.tv/kraken?oauth_token=[...]
                                               // 这里记录了Twitch的API: https://github.com/justintv/Twitch-API
            }
        ]
    }
}

验证

检查 accessToken 是否可以使用Minecraft服务器进行身份验证。Minecraft启动器(从版本1.6.13开始) 在启动时调用此端点，以验证其保存的令牌仍然可用，如果返回错误，则调用 /refresh。

注意，accessToken 可能无法与Minecraft服务器进行身份验证，但是对于 /refresh 来说还是不错的。这主要发生在使用另一个客户端时(e.g. 在另一台电脑上玩Minecraft)。似乎只有最近获得的给定帐户的 accessToken才能被可靠地用于身份验证。(倒数第二的令牌似乎也仍然有效，但是不要依赖它)。

在有或没有 clientToken 的情况下/validate 都可能被调用。 如果提供了 clientToken，应该匹配一个用于获取 accessToken。Minecraft启动器发送一个clientToken 到 /validate。(翻译水平不足，无法理解请阅读英文原文)

端点

/validate

有效载荷

{
    "accessToken": "valid accessToken",
    "clientToken": "associated clientToken" // 可选，见上图
}

响应

如果成功，则返回一个空的有效载荷 (204 No Content) ， 否则将显示状态为 403 Forbidden 的JSON错误。

注销

无效的 accessToken 使用一个帐户的用户名和密码

端点

/signout

有效载荷

{
    "username": "mojang account name",
    "password": "mojang account password"
}

响应

如果成功返回一个空的有效载荷。

无效

无效的 accessToken 使用客户端/访问令牌。

端点

/invalidate

有效载荷

{
    "accessToken": "valid accessToken",
    "clientToken": "client identifier"   // 这需要与最初获得的accessToken相同
                                         // 
}

响应

如果成功返回一个空的有效载荷。

加入一个服务器

查看Protocol Encryption#Authentication