imported>Sadimusi |
imported>Oxodao |
| (97 intermediate revisions by 24 users not shown) |
| Line 1: |
Line 1: |
| The minecraft client and server communicate with Mojang to validate player sessions. This page describes some of the operations.
| | #REDIRECT [[Legacy Mojang Authentication]] |
| | |
| == Authentication ==
| |
| | |
| Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the [[Legacy_Authentication|previous authentication system]].
| |
| | |
| === 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>
| |
| | |
| === Session ID ===
| |
| | |
| Whenever a Mojang service requires a session ID, you can simply combine a valid <code>accessToken</code> with a profile identifier as follows:
| |
| | |
| token:<accessToken>:<profile ID>
| |
| | |
| === Authenticate ===
| |
| | |
| This method is used whenever a user tries to log in 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 ===
| |
| | |
| This method is used to refresh an expired but 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
| |
| }
| |
| </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>
| |
| | |
| | |
| == Joining a Server ==
| |
| | |
| See [[Protocol Encryption]] for details on encrypting connections.
| |
| | |
| === Client operation ===
| |
| | |
| # Client connects to server
| |
| # Client sends a [[Protocol#0x02|0x02 handshake]] containing the current player name
| |
| # Client receives an [[Protocol#0xFD|0xFD encryption request]] with the server's public key and four verification bytes.
| |
| # Client generates a symmetric key.
| |
| # Client sends a HTTP request to
| |
| #:<pre>http://session.minecraft.net/game/joinserver.jsp?user=<player name>&sessionId=<session id>&serverId=<server hash></pre>
| |
| #:Note: See the [[#Session ID|Session ID]] section on how the <code><session id></code> is generated.
| |
| #:If the response is '''OK''' then continue, otherwise stop
| |
| # Client sends [[Protocol#0xFC|0xFC encryption response]] - client encrypts shared secret and verification token with the server's public key
| |
| # Server checks validity and sends [[Protocol#0xFC|0xFC encryption response]] with two empty arrays
| |
| # Both sides enable AES/CFB2 encryption using the shared secret generated by the client
| |
| # Client sends [[Protocol#0xCD|0xCD client status]] with a payload of 0 (ready to spawn)
| |
| # Server sends [[Protocol#0x01|0x01 login]]
| |
| # ... receive map chunks, etc...
| |
| | |
| === Server operation ===
| |
| | |
| # Server generates a 1024-bit RSA keypair.
| |
| # ...
| |
| # Server answers TCP connection request and receives a [[Protocol#0x02|0x02 handshake]] from the client.
| |
| # Server sends [[Protocol#0xFD|0xFD encryption request]] with its public key and a verification token.
| |
| # Server receives [[Protocol#0xFC|0xFC encryption response]] from client and decrypts the shared secret.
| |
| # Server verifies the validity of the verification token. If this isn't verified, it kicks the client.
| |
| # Server sends a HTTP request to
| |
| #:<pre>http://session.minecraft.net/game/checkserver.jsp?user=<username>&serverId=<server hash></pre>
| |
| #:If it returns '''YES''' then the client is authenticated and allowed to join. Otherwise the client will/should be [[Protocol#0xFF|kicked]] with “Failed to verify username!”
| |
| # Server sends a [[Protocol#0xFC|0xFC encryption response]] packet with two empty arrays.
| |
| # Both sides enable AES/CFB2 encryption.
| |
| # Server receives [[Protocol#0xCD|0xCD client status]] with a payload of , indicating "ready to spawn"
| |
| # Server sends [[Protocol#0x01|0x01 login]]
| |
| # ... send map chunks, etc...
| |
| | |
| [[Category:Protocol Details]]
| |
| [[Category:Minecraft Modern]]
| |