imported>Nickelpro1 |
imported>Oxodao |
| (76 intermediate revisions by 21 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]].
| | #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>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
| |
| |}
| |
| | |
| == Session ID ==
| |
| | |
| Whenever a Mojang service requires a session ID, you can simply combine a valid <code>accessToken</code> with the corresponding profile identifier as follows:
| |
| | |
| token:<accessToken>:<profile ID>
| |
| | |
| == Authenticate ==
| |
| | |
| Authenticates a user using his password.
| |
| | |
| === Endpoint ===
| |
| /authenticate
| |
| | |
| === Payload ===
| |
| <syntaxhighlight lang="javascript">
| |
| {
| |
| "agent": { // optional
| |
| "name": "Minecraft", // So far this is the only encountered value
| |
| "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"
| |
| }
| |
| ],
| |
| "selectedProfile": { // only present if the agent field was received
| |
| "id": "profile identifier",
| |
| "name": "player name"
| |
| }
| |
| }
| |
| </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.
| |
| | |
| == 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 valid.
| |
| | |
| === 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]]
| |
| | |
| | |
| [[Category:Protocol Details]]
| |
| [[Category:Minecraft Modern]]
| |