Zh:Authentication

Minecraft 1.6 引入了一个名为 Yggdrasil验证方案 来完全替代 先前的验证系统. Mojang的其他游戏, Scrolls, 也使用此验证方法. Mojang 说 每个人都应该使用这个验证系统进行自定义登录, 但是 不会向用户索要凭据.

请求格式

所有的 Yggdrasil 请求都发送到下列服务器

https://authserver.mojang.com

此外，他们应该遵循以下规则

• 使用 POST 请求
• 包含 Content-Type 头，并设置为 application/json
• 包含一个使用 JSON 格式编码的有效载荷

如果请求成功，服务器将做出如下响应

• 状态码 200
• 一个符合下文规范的 JSON数据

如果请求失败，服务器将做出如下响应

• 恰当的非200状态码 HTTP status code
• 一个包含如下信息的JSON数据

{
    "error": "简短的描述(机器可读)",
    "errorMessage": "一个向用户展示的错误消息（人类可读）",
    "cause": "引起错误的原因" // 可选
}

错误

以下是一些可能遇到的错误：

错误	原因	错误消息	注释
Method Not Allowed		请求所使用的方法不允许访问当前URI，这里通常是由于非POST方法引起的。
Not Found		服务器没有找到URI所对应的资源
ForbiddenOperationException	UserMigratedException	无效的凭证。账户已迁移。请使用电子邮件作为用户名。
ForbiddenOperationException		无效的凭证。用户名或密码无效。
ForbiddenOperationException		无效的凭证。	使用同一用户名进行了太多的登录尝试(参见 /authenticate)。注释:用户名密码也许是有效的。
ForbiddenOperationException		Invalid token.	accessToken was invalid.
IllegalArgumentException		Access token already has a profile assigned.	Selecting profiles isn't implemented yet.
IllegalArgumentException		credentials is null	Username/password was not submitted.
IllegalArgumentException		Invalid salt version	???
Unsupported Media Type		The server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method	Data was not submitted as application/json

Authenticate

Authenticates a user using their password.

Endpoint

/authenticate

Payload

{
    "agent": {                              // defaults to Minecraft
        "name": "Minecraft",                // For Mojang's other game Scrolls, "Scrolls" should be used
        "version": 1                        // This number might be increased
                                            // by the vanilla client in the future
    },
    "username": "mojang account name",      // Can be an email address or player name for
                                            // unmigrated accounts
    "password": "mojang account password",
    "clientToken": "client identifier",     // optional
    "requestUser": true                     // optional; default: false; true adds the user object to the response
}

The clientToken should be a randomly generated identifier and must be identical for each request. The vanilla launcher generates a random (version 4) UUID on first run and saves it, reusing it for every subsequent request. In case it is omitted the server will generate a random token based on Java's UUID.toString() which should then be stored by the client. This will however also invalidate all previously acquired accessTokens for this user across all clients.

Response

{
    "accessToken": "random access token",      // hexadecimal or JSON-Web-Token (unconfirmed) [The normal accessToken can be found in the payload of the JWT (second by '.' separated part as Base64 encoded JSON object), in key "yggt"]
    "clientToken": "client identifier",        // identical to the one received
    "availableProfiles": [                     // only present if the agent field was received
        {
            "agent": "minecraft",              // Presumably same value as before
            "id": "profile identifier",        // hexadecimal
            "name": "player name",
            "userId": "hex string",
            "createdAt": 1325376000000,        // Milliseconds since Jan 1 1970
            "legacyProfile": true or false,    // Present even when false
            "suspended": true or false,        // probably false
            "paid": true or false,             // probably true
            "migrated": true or false,         // Seems to be false even for migrated accounts...?  (https://bugs.mojang.com/browse/WEB-1461)
            "legacy": true or false            // Only appears in the response if true. Default to false.  Redundant to the newer legacyProfile...
        }
    ],
    "selectedProfile": {                       // only present if the agent field was received
        "id": "uuid without dashes",
        "name": "player name",
        "userId": "hex string",
        "createdAt": 1325376000000,
        "legacyProfile": true or false,
        "suspended": true or false,
        "paid": true or false,
        "migrated": true or false,
        "legacy": true or false
    },
    "user": {                                  // only present if requestUser was true in the request payload
        "id": "user identifier",               // hexadecimal
        "email": "user@email.example",         // Hashed(?) value for unmigrated accounts
        "username": "user@email.example",      // Regular name for unmigrated accounts, email for migrated ones
        "registerIp": "198.51.100.*",          // IP address with the last digit censored
        "migratedFrom": "minecraft.net",
        "migratedAt": 1420070400000,
        "registeredAt": 1325376000000,         // May be a few minutes earlier than createdAt for profile
        "passwordChangedAt": 1569888000000,
        "dateOfBirth": -2208988800000,
        "suspended": false,
        "blocked": false,
        "secured": true,
        "migrated": false,                     // Seems to be false even when migratedAt and migratedFrom are present...
        "emailVerified": true,
        "legacyUser": false,
        "verifiedByParent": false,
        "properties": [
            {
                "name": "preferredLanguage",   // might not be present for all accounts
                "value": "en"                  // Java locale format (https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toString--)
            },
            {
                "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
            }
        ]
    }
}

Note: If a user wishes to stay logged in on their computer you are strongly advised to store the received accessToken instead of the password itself.

Currently each account will only have one single profile, multiple profiles per account are however planned in the future. If a user attempts to log into a valid Mojang account with no attached Minecraft license, the authentication will be successful, but the response will not contain a selectedProfile field, and the availableProfiles array will be empty.

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"                  // Java locale format (https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toString--)
            },
            {
                "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

Payload

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

Response

Returns an empty payload if successful.

Invalidate

Invalidates accessTokens using a client/access token pair.

Endpoint

/invalidate

Payload

{
    "accessToken": "valid accessToken",
    "clientToken": "client identifier"   // This needs to be identical to the one used
                                         // to obtain the accessToken in the first place
}

Response

Returns an empty payload if successful.

Joining a Server

See Protocol Encryption#Authentication