Difference between revisions of "Authentication"

From wiki.vg
Jump to navigation Jump to search
(Added some common errors)
(Removed another redundant section)
Line 1: Line 1:
The minecraft client and server communicate with Mojang to validate player sessions. This page describes some of the operations.
 
 
== Authentication ==
 
 
 
Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the [[Legacy_Authentication|previous authentication system]].
 
Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the [[Legacy_Authentication|previous authentication system]].
  
=== Request format ===
+
== Request format ==
  
 
All requests to Yggdrasil are made to the following server:
 
All requests to Yggdrasil are made to the following server:
Line 34: Line 30:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
+
== Errors ==
=== Errors ===
 
 
These are some of the errors that can be encountered:
 
These are some of the errors that can be encountered:
 
{| class="wikitable"
 
{| class="wikitable"
Line 75: Line 70:
 
|}
 
|}
  
 +
== Session ID ==
  
=== 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:
 
 
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>
 
   token:<accessToken>:<profile ID>
  
 
+
== Authenticate ==
=== Authenticate ===
 
  
 
Authenticates a user using his password.
 
Authenticates a user using his password.
  
==== Endpoint ====
+
=== Endpoint ===
 
   /authenticate
 
   /authenticate
  
==== Payload ====
+
=== Payload ===
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
Line 108: Line 101:
 
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.
 
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 ====
+
=== Response ===
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
Line 129: Line 122:
 
Currently each account will only have one single profile, multiple profiles per account are however planned in the future.
 
Currently each account will only have one single profile, multiple profiles per account are however planned in the future.
  
 
+
== Refresh ==
=== 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]]).  
 
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 ====
+
=== Endpoint ===
 
   /refresh
 
   /refresh
  
==== Payload ====
+
=== Payload ===
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
Line 152: Line 144:
 
Note: The provided <code>accessToken</code> gets invalidated.
 
Note: The provided <code>accessToken</code> gets invalidated.
  
==== Response ====
+
=== Response ===
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
Line 164: Line 156:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
+
== Validate ==
=== Validate ===
 
  
 
Checks if an <code>accessToken</code> is valid.
 
Checks if an <code>accessToken</code> is valid.
  
==== Endpoint ====
+
=== Endpoint ===
 
   /validate
 
   /validate
  
==== Payload ====
+
=== Payload ===
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
Line 179: Line 170:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
==== Response ====
+
=== Response ===
 
Unlike most other methods this one will return an empty payload if successful.
 
Unlike most other methods this one will return an empty payload if successful.
  
 
== Joining a Server ==
 
== Joining a Server ==
  
See [[Protocol Encryption]] for details on encrypting connections.
+
See [[Protocol Encryption#Authentication|Protocol Encryption]]
 
 
=== 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>&lt;session id&gt;</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:Protocol Details]]
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]

Revision as of 14:27, 16 July 2013

Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the 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 POST requests
  • Have the Content-Type header set to application/json
  • Contain a JSON-encoded dictionary as payload

If a request was successful the server will respond with:

  • Status code 200
  • A JSON-encoded dictionary according to the specifications below

If however a request fails, the server will respond with:

{
  "error": "Short description of the error",
  "errorMessage": "Longer description which can be shown to the user",
  "cause": "Cause of the error"        // optional
}

Errors

These are some of the errors that can be encountered:

Error Cause Error message Notes
Method Not Allowed 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.
Not Found The server has not found anything matching the request URI Non-existing endpoint was called.
ForbiddenOperationException UserMigratedException Invalid credentials. Account migrated, use e-mail as username.
ForbiddenOperationException Invalid credentials. Invalid username or password.
ForbiddenOperationException Invalid token. accessToken was invalid.
IllegalArgumentException Access token already has a profile assigned. Selecting profiles isn't implemented yet.

Session ID

Whenever a Mojang service requires a session ID, you can simply combine a valid accessToken with the corresponding profile identifier as follows:

 token:<accessToken>:<profile ID>

Authenticate

Authenticates a user using his password.

Endpoint

 /authenticate

Payload

{
  "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
}

The clientToken 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 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
  "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"
  }
}

Note: If a user wishes to stay logged in on his 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.

Refresh

Refreshes a valid accessToken. 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

{
  "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"
  }
}

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"
  }
}

Validate

Checks if an accessToken is valid.

Endpoint

 /validate

Payload

{
  "accessToken": "valid accessToken",
}

Response

Unlike most other methods this one will return an empty payload if successful.

Joining a Server

See Protocol Encryption