imported>Thinkofdeath |
imported>Oxodao |
| (35 intermediate revisions by 14 users not shown) |
| Line 1: |
Line 1: |
| Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the [[Legacy_Authentication|previous authentication system]]. Mojang's other game, Scrolls, uses this method of authentication as well. Mojang has said that this Authentication system should be used by everyone for custom logins[https://twitter.com/KrisJelbring/status/453573406341206016], but credentials should never be collected from users[https://twitter.com/KrisJelbring/status/461390585086361600].
| | #REDIRECT [[Legacy Mojang Authentication]] |
| | |
| == Request format ==
| |
| | |
| All requests to Yggdrasil are made to the following server:
| |
| | |
| https://authserver.mojang.com
| |
| | |
| Further, they are expected to fulfill the following rules:
| |
| | |
| * Are <code>POST</code> requests
| |
| * Have the <code>Content-Type</code> header set to <code>application/json</code>
| |
| * Contain a [http://json.org JSON]-encoded dictionary as payload
| |
| | |
| If a request was successful the server will respond with:
| |
| | |
| * Status code <code>200</code>
| |
| * A [http://json.org JSON]-encoded dictionary according to the specifications below
| |
| | |
| If however a request fails, the server will respond with:
| |
| | |
| * An appropriate, non-200 [http://en.wikipedia.org/wiki/List_of_HTTP_status_codes HTTP status code]
| |
| * A [http://json.org JSON]-encoded dictionary following this format:
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "error": "Short description of the error",
| |
| "errorMessage": "Longer description which can be shown to the user",
| |
| "cause": "Cause of the error" // optional
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| == Errors ==
| |
| These are some of the errors that can be encountered:
| |
| {| class="wikitable"
| |
| |-
| |
| ! Error
| |
| ! Cause
| |
| ! Error message
| |
| ! Notes
| |
| |-
| |
| | <code>Method Not Allowed</code>
| |
| |
| |
| | The method specified in the request is not allowed for the resource identified by the request URI
| |
| | Something other than a POST request was received.
| |
| |-
| |
| | <code>Not Found</code>
| |
| |
| |
| | The server has not found anything matching the request URI
| |
| | Non-existing endpoint was called.
| |
| |-
| |
| | <code>ForbiddenOperationException</code>
| |
| | <code>UserMigratedException</code>
| |
| | Invalid credentials. Account migrated, use e-mail as username.
| |
| |
| |
| |-
| |
| | <code>ForbiddenOperationException</code>
| |
| |
| |
| | Invalid credentials. Invalid username or password.
| |
| |
| |
| |-
| |
| | <code>ForbiddenOperationException</code>
| |
| |
| |
| | Invalid token.
| |
| | <code>accessToken</code> was invalid.
| |
| |-
| |
| | <code>IllegalArgumentException</code>
| |
| |
| |
| | Access token already has a profile assigned.
| |
| | Selecting profiles isn't implemented yet.
| |
| |-
| |
| | <code>IllegalArgumentException</code>
| |
| |
| |
| | credentials can not be null.
| |
| | Username/password was not submitted.
| |
| |-
| |
| | <code>Unsupported Media Type</code>
| |
| |
| |
| | 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 his password.
| |
| | |
| === Endpoint ===
| |
| /authenticate
| |
| | |
| === Payload ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "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
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| The <code>clientToken</code> should be a randomly generated identifier and must be identical for each request.
| |
| In case it is omitted the server will generate a random token based on Java's [http://docs.oracle.com/javase/7/docs/api/java/util/UUID.html#toString() UUID.toString()] which should then be stored by the client. This will however also invalidate all previously acquired <code>accessToken</code>s for this user across all clients.
| |
| | |
| === Response ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "accessToken": "random access token", // hexadecimal
| |
| "clientToken": "client identifier", // identical to the one received
| |
| "availableProfiles": [ // only present if the agent field was received
| |
| {
| |
| "id": "profile identifier", // hexadecimal
| |
| "name": "player name",
| |
| "legacy": true or false // In practice, this field only appears in the response if true. Default to false.
| |
| }
| |
| ],
| |
| "selectedProfile": { // only present if the agent field was received
| |
| "id": "profile identifier",
| |
| "name": "player name",
| |
| "legacy": true or false
| |
| }
| |
| }
| |
| </syntaxhighlight>
| |
| '''Note:''' If a user wishes to stay logged in on his computer you are strongly advised to store the received <code>accessToken</code> 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.
| |
| | |
| == Refresh ==
| |
| | |
| Refreshes a valid <code>accessToken</code>. It can be uses 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 ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "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"
| |
| }
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| Note: The provided <code>accessToken</code> gets invalidated.
| |
| | |
| === Response ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "accessToken": "random access token", // hexadecimal
| |
| "clientToken": "client identifier", // identical to the one received
| |
| "selectedProfile": {
| |
| "id": "profile identifier", // hexadecimal
| |
| "name": "player name"
| |
| }
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| == Validate ==
| |
| | |
| Checks if an <code>accessToken</code> is a valid session token with a currently-active session. Note: this method will not respond successfully to all currently-logged-in sessions, just the most recently-logged-in for each user. It is intended to be used by servers to validate that a user should be connecting (and reject users who have logged in elsewhere since starting Minecraft), NOT to auth that a particular session token is valid for authentication purposes. To authenticate a user by session token, use the refresh verb and catch resulting errors.
| |
| | |
| === Endpoint ===
| |
| /validate
| |
| | |
| === Payload ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "accessToken": "valid accessToken",
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| === Response ===
| |
| Returns an empty payload if successful.
| |
| | |
| == Signout ==
| |
| | |
| Invalidates <code>accessToken</code>s using an account's username and password.
| |
| | |
| === Endpoint ===
| |
| /signout
| |
| | |
| === Payload ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "username": "mojang account name",
| |
| "password": "mojang account password",
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| === Response ===
| |
| Returns an empty payload if successful.
| |
| | |
| == Invalidate ==
| |
| | |
| Invalidates <code>accessToken</code>s using a client/access token pair.
| |
| | |
| === Endpoint ===
| |
| /invalidate
| |
| | |
| === Payload ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "accessToken": "valid accessToken",
| |
| "clientToken": "client identifier" // This needs to be identical to the one used
| |
| // to obtain the accessToken in the first place
| |
| }
| |
| </syntaxhighlight>
| |
| | |
| === Response ===
| |
| Returns an empty payload if successful.
| |
| | |
| == Joining a Server ==
| |
| | |
| See [[Protocol Encryption#Authentication|Protocol Encryption]]
| |