User:Lzs/Authentication(Chinese)

(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 数组将为空。

Some instances in the wild have been observed of Mojang returning a flat null for failed refresh attempts against legacy accounts. It's not clear what the actual error tied to the null response is and it is extremely rare, but implementations should be wary of null output from the response.

This endpoint is severely rate-limited: multiple /authenticate requests for the same account in a short amount of time (think 3 requests in a few seconds), even with the correct password, will eventually lead to an Invalid credentials. response. This error clears up a few seconds later.

Refresh

Refreshes a valid accessToken. It can be used to keep a user logged in between gaming sessions and is preferred over storing the user's password in a file (see lastlogin).

Endpoint

/refresh

Payload

{
    "accessToken": "valid accessToken",
    "clientToken": "client identifier",  // This needs to be identical to the one used
                                         // to obtain the accessToken in the first place
    "selectedProfile": {                 // optional; sending it will result in an error
        "id": "profile identifier",      // hexadecimal
        "name": "player name"
    },
    "requestUser": true                  // optional; default: false; true adds the user object to the response
}

Note: The provided accessToken gets invalidated.

Response

{
    "accessToken": "random access token",      // hexadecimal
    "clientToken": "client identifier",        // identical to the one received
    "selectedProfile": {
        "id": "profile identifier",            // hexadecimal
        "name": "player name"
    },
    "user": {                                  // only present if requestUser was true in the request payload
        "id": "user identifier",               // hexadecimal
        "properties": [
            {
                "name": "preferredLanguage",   // might not be present for all accounts
                "value": "en"                  // ISO 639-1?
            },
            {
                "name": "twitch_access_token", // only present if a twitch account is associated (see https://account.mojang.com/me/settings)
                "value": "twitch oauth token"  // OAuth 2.0 Token; alphanumerical; e.g. https://api.twitch.tv/kraken?oauth_token=[...]
                                               // the Twitch API is documented here: https://github.com/justintv/Twitch-API
            }
        ]
    }
}

Validate

Checks if an accessToken is usable for authentication with a Minecraft server. The Minecraft Launcher (as of version 1.6.13) calls this endpoint on startup to verify that its saved token is still usable, and calls /refresh if this returns an error.

Note that an accessToken may be unusable for authentication with a Minecraft server, but still be good enough for /refresh. This mainly happens when one has used another client (e.g. played Minecraft on another PC with the same account). It seems only the most recently obtained accessToken for a given account can reliably be used for authentication (the next-to-last token also seems to remain valid, but don't rely on it).

/validate may be called with or without a clientToken. If a clientToken is provided, it should match the one used to obtain the accessToken. The Minecraft Launcher does send a clientToken to /validate.

Endpoint

/validate

Payload

{
    "accessToken": "valid accessToken",
    "clientToken": "associated clientToken" // optional, see above
}

Response

Returns an empty payload (204 No Content) if successful, an error JSON with status 403 Forbidden otherwise.

Signout

Invalidates accessTokens using an account's username and password.

Endpoint

/signout

有效载荷

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

响应

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

无效

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

端点

/invalidate

有效载荷

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

响应

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

加入一个服务器

查看Protocol Encryption#Authentication