Difference between revisions of "Legacy Mojang Authentication"
(→Response: mention rate-limiting present on /authenticate) |
(→Errors: add "Invalid credentials." message obtained when /authenticate rate-limits) |
||
Line 61: | Line 61: | ||
| Invalid credentials. Invalid username or password. | | Invalid credentials. Invalid username or password. | ||
| | | | ||
+ | |- | ||
+ | | <code>ForbiddenOperationException</code> | ||
+ | | | ||
+ | | Invalid credentials. | ||
+ | | Too many login attempts with this username recently (see <code>/authenticate</code>). Note that username and password may still be valid! | ||
|- | |- | ||
| <code>ForbiddenOperationException</code> | | <code>ForbiddenOperationException</code> |
Revision as of 22:05, 15 August 2015
Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the 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, but credentials should never be collected from users.
Contents
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
}
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 credentials. | Too many login attempts with this username recently (see /authenticate ). Note that username and password may still be valid!
| |
ForbiddenOperationException
|
Invalid token. | accessToken was invalid.
| |
IllegalArgumentException
|
Access token already has a profile assigned. | Selecting profiles isn't implemented yet. | |
IllegalArgumentException
|
credentials is null | Username/password was not submitted. | |
Unsupported Media Type
|
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 their password.
Endpoint
/authenticate
Payload
{
"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
}
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",
"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
}
}
Note: If a user wishes to stay logged in on their 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. 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.
This endpoint is severely rate-limited: multiple /authenticate
requests for the same account in a short amount of time (think 3 requests in a few seconds), even with the correct password, will eventually lead to an Invalid credentials.
response. This error clears up a few seconds later.
Refresh
Refreshes a valid accessToken
. It can be used 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 usable for authentication with a Minecraft server. The Minecraft Launcher (as of version 1.6.13) calls this endpoint on startup to verify that its saved token is still usable, and calls /refresh
if this returns an error.
Note that an accessToken
may be unusable for authentication with a Minecraft server, but still be good enough for /refresh
. This mainly happens when one has used another client (e.g. played Minecraft on another PC with the same account). It seems only the most recently obtained accessToken
for a given account can reliably be used for authentication (the next-to-last token also seems to remain valid, but don't rely on it).
/validate
may be called with or without a clientToken
. If a clientToken
is provided, it should match the one used to obtain the accessToken
. The Minecraft Launcher does send a clientToken
to /validate
.
Endpoint
/validate
Payload
{
"accessToken": "valid accessToken"
"clientToken": "associated clientToken" // optional, see above
}
Response
Returns an empty payload (204 No Content
) if successful, an error JSON with status 403 Forbidden
otherwise.
Signout
Invalidates accessToken
s using an account's username and password.
Endpoint
/signout
Payload
{
"username": "mojang account name",
"password": "mojang account password"
}
Response
Returns an empty payload if successful.
Invalidate
Invalidates accessToken
s using a client/access token pair.
Endpoint
/invalidate
Payload
{
"accessToken": "valid accessToken",
"clientToken": "client identifier" // This needs to be identical to the one used
// to obtain the accessToken in the first place
}
Response
Returns an empty payload if successful.