Difference between revisions of "Session"
m (Fixed session ID section) |
(Added refresh method + removed sections which were moved to their own pages) |
||
Line 34: | Line 34: | ||
</syntaxhighlight> | </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: | Whenever a Mojang service requires a session ID, you can simply combine a valid <code>accessToken</code> with a profile identifier as follows: | ||
Line 41: | Line 41: | ||
=== Authenticate === | === Authenticate === | ||
+ | |||
This method is used whenever a user tries to log in using his password. | This method is used whenever a user tries to log in using his password. | ||
Line 49: | Line 50: | ||
<syntaxhighlight lang="javascript"> | <syntaxhighlight lang="javascript"> | ||
{ | { | ||
− | "agent": { | + | "agent": { // optional |
"name": "Minecraft", // So far this is the only encountered value | "name": "Minecraft", // So far this is the only encountered value | ||
"version": 1 // This number might be increased | "version": 1 // This number might be increased | ||
Line 61: | Line 62: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | The <code>clientToken</code> should be a randomly generated identifier and must identical for each request. | + | 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. | + | 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 ==== | ||
Line 69: | Line 71: | ||
"accessToken": "random access token", // hexadecimal | "accessToken": "random access token", // hexadecimal | ||
"clientToken": "client identifier", // identical to the one received | "clientToken": "client identifier", // identical to the one received | ||
− | "availableProfiles": [ | + | "availableProfiles": [ // only present if the agent field was received |
{ | { | ||
"id": "profile identifier", // hexadecimal | "id": "profile identifier", // hexadecimal | ||
Line 75: | Line 77: | ||
} | } | ||
], | ], | ||
− | "selectedProfile": { | + | "selectedProfile": { // only present if the agent field was received |
"id": "profile identifier", | "id": "profile identifier", | ||
"name": "player name" | "name": "player name" | ||
Line 85: | Line 87: | ||
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 === | ||
− | + | 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 == | == Joining a Server == |
Revision as of 16:21, 15 July 2013
The minecraft client and server communicate with minecraft.net to validate player sessions. This page describes some of the operations.
Contents
Authentication
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 toapplication/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:
- An appropriate, non-200 HTTP status code
- A JSON-encoded dictionary following this format:
{
"error": "Short description of the error",
"errorMessage": "Longer description which can be shown to the user",
"cause": "Cause of the error" // optional
}
Session ID
Whenever a Mojang service requires a session ID, you can simply combine a valid accessToken
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
{
"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 accessToken
s 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
This method is used to refresh an expired but 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
}
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"
}
}
Joining a Server
See Protocol Encryption for details on encrypting connections.
Client operation
- Client connects to server
- Client sends a 0x02 handshake containing the current player name
- Client receives an 0xFD encryption request with the server's public key and four verification bytes.
- Client generates a symmetric key.
- Client sends a HTTP request to
http://session.minecraft.net/game/joinserver.jsp?user=<player name>&sessionId=<session id>&serverId=<server hash>
- Note: See the Session ID section on how the
<session id>
is generated. - If the response is OK then continue, otherwise stop
- Client sends 0xFC encryption response - client encrypts shared secret and verification token with the server's public key
- Server checks validity and sends 0xFC encryption response with two empty arrays
- Both sides enable AES/CFB2 encryption using the shared secret generated by the client
- Client sends 0xCD client status with a payload of 0 (ready to spawn)
- Server sends 0x01 login
- ... receive map chunks, etc...
Server operation
- Server generates a 1024-bit RSA keypair.
- ...
- Server answers TCP connection request and receives a 0x02 handshake from the client.
- Server sends 0xFD encryption request with its public key and a verification token.
- Server receives 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
http://session.minecraft.net/game/checkserver.jsp?user=<username>&serverId=<server hash>
- If it returns YES then the client is authenticated and allowed to join. Otherwise the client will/should be kicked with “Failed to verify username!”
- Server sends a 0xFC encryption response packet with two empty arrays.
- Both sides enable AES/CFB2 encryption.
- Server receives 0xCD client status with a payload of , indicating "ready to spawn"
- Server sends 0x01 login
- ... send map chunks, etc...
Outdated authentication system
This system was used by Minecraft versions prior to 1.6 and might be discontinued at any moment without warning.
Login
To log the player in, the official launcher sends an HTTPS POST (GET appears to suffice as well) request to:
https://login.minecraft.net
with the postdata:
?user=<username>&password=<password>&version=<launcher version>
and a "application/x-www-form-urlencoded" Content-Type header.
After migrating to Mojang accounts, email address is used instead of username, but the procedure stays the same.
The current launcher version is "13" (for new launcher it's "14"), sending a value lower than 12 will cause the server to return "Old version", however you can send any large number and it will return as expected. If the login succeeded, it will return 5 ':' delimited values.
1343825972000:deprecated:SirCmpwn:7ae9007b9909de05ea58e94199a33b30c310c69c:dba0c48e1c584963b9e93a038a66bb98
- current version of the game files (not the launcher itself). This is a unix timestamp which the launcher compares to the ~/.minecraft/bin/version file.
- Previously contained a download ticket for requesting new versions of minecraft.jar from the server. Now contains only "deprecated".
- case-correct username. For mojang accounts, the user's actual username is returned here instead of the email used to log in.
- sessionId - a unique ID for your current session.
- UID - currently unused, introduced near August 8th, 2012. Grum says this is the unique ID for the user, potentially for changing Minecraft names in future.
If the request is missing a parameter, the server will return "Bad response". If the login information is incorrect, the server will return "Bad login". If the login information is correct but the account isn't premium, the server will return "User not premium". If your minecraft.net account has been migrated to a Mojang account but you're logging in with your minecraft.net username the server will return "Acount migrated, use e-mail".
Keep-alive
Every 6000 ticks, the client sends an HTTPS request to
https://login.minecraft.net/session?name=<username>&session=<session id>
The client discards the server's response.