Difference between revisions of "Legacy Mojang Authentication"
Barneygale (talk | contribs) (New authentication write-up at Session, adding redirect) |
m (Remove Category:Protocol Details.) |
||
(62 intermediate revisions by 37 users not shown) | |||
Line 1: | Line 1: | ||
− | # | + | With the release of Minecraft 1.6, Mojang introduced a new authentication system called '''Yggdrasil''', which replaced the previous [[Legacy Authentication|Legacy authentication system]]. This authentication system is also used in Mojang's other game, Scrolls. According to Mojang, the Yggdrasil authentication system should be adopted by developers for custom login implementation, but they strongly advise against collecting credentials from users. For those utilizing newer Microsoft accounts, there is an alternative authentication scheme available called the [[Microsoft Authentication Scheme|Microsoft authentication scheme]]. |
+ | |||
+ | == Requests == | ||
+ | The Yggdrasil authentication system requests are made to the following server: | ||
+ | |||
+ | https://authserver.mojang.com | ||
+ | |||
+ | To ensure successful requests, they must adhere to the following guidelines: | ||
+ | * Use a <code>POST</code> request method | ||
+ | * Include a <code>Content-Type</code> header set to <code>application/json</code> | ||
+ | * Contain a [[wikipedia:JSON|JSON]]-encoded dictionary as payload | ||
+ | |||
+ | In the event of a successful request, the server will return: | ||
+ | * A <code>2XX</code> [[wikipedia:List of HTTP status codes|HTTP status code]] to indicate success | ||
+ | * An empty payload or a [[wikipedia:JSON|JSON]]-encoded dictionary as specified in the API documentation | ||
+ | |||
+ | In the case of a failed request, the server will respond with: | ||
+ | * An [[wikipedia:List of HTTP status codes|HTTP status code]] other than <code>2XX</code> to indicate failure | ||
+ | * A [[wikipedia:JSON|JSON]]-encoded dictionary following the format below: | ||
+ | <syntaxhighlight lang="javascript"> | ||
+ | { | ||
+ | "error": "Short description of the error", | ||
+ | "cause": "Cause of the error" // optional | ||
+ | "errorMessage": "Longer description which can be shown to the user", | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | == Errors == | ||
+ | The following are examples of error scenarios that may occur during the use of the Yggdrasil authentication system: | ||
+ | |||
+ | {| class="wikitable" | ||
+ | |- | ||
+ | ! STATUS | ||
+ | ! error | ||
+ | ! cause | ||
+ | ! errorMessage | ||
+ | ! NOTES | ||
+ | |- | ||
+ | | <code>415 Unsupported Media Type</code> | ||
+ | | <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 | ||
+ | | An attempt to send a POST request with incorrect request headers to any endpoint. | ||
+ | |- | ||
+ | | <code>405 Method Not Allowed</code> | ||
+ | | <code>Method Not Allowed</code> | ||
+ | | | ||
+ | | The method specified in the request is not allowed for the resource identified by the request URI | ||
+ | | An attempt to use a request method other than <code>POST</code> to access any of the endpoints. | ||
+ | |- | ||
+ | | <code>404 Not Found</code> | ||
+ | | <code>Not Found</code> | ||
+ | | | ||
+ | | The server has not found anything matching the request URI | ||
+ | | An attempt to send a request to a non-existent endpoint. | ||
+ | |- | ||
+ | | <code>410 Gone</code> | ||
+ | | <code>GoneException</code> | ||
+ | | | ||
+ | | Migrated | ||
+ | | A successful attempt to sign in using a migrated Mojang account. | ||
+ | |- | ||
+ | | <code>403 Forbidden</code> | ||
+ | | <code>ForbiddenOperationException</code> | ||
+ | | | ||
+ | | Forbidden | ||
+ | | An attempt to sign in using empty or insufficiently short credentials. | ||
+ | |- | ||
+ | | <code>403 Forbidden</code> | ||
+ | | <code>ForbiddenOperationException</code> | ||
+ | | | ||
+ | | Invalid credentials. Invalid username or password. | ||
+ | | Either a successful attempt to sign in using an account with excessive login attempts or an unsuccessful attempt to sign in using a non-existent account. | ||
+ | |- | ||
+ | | <code>403 Forbidden</code> | ||
+ | | <code>ForbiddenOperationException</code> | ||
+ | | | ||
+ | | Invalid credentials. Legacy account is non-premium account. | ||
+ | | An unsuccessful attempt to sign in using a Legacy account without a valid Minecraft purchase. | ||
+ | |- | ||
+ | | <code>403 Forbidden</code> | ||
+ | | <code>ForbiddenOperationException</code> | ||
+ | | <code>UserMigratedException</code> | ||
+ | | Invalid credentials. Account migrated, use email as username. | ||
+ | | An unsuccessful attempt to sign in using a migrated Legacy account. | ||
+ | |- | ||
+ | | <code>403 Forbidden</code> | ||
+ | | <code>TooManyRequestsException</code> | ||
+ | | | ||
+ | | Token does not exist | ||
+ | | An attempt to refresh an access token that has been invalidated, no longer exists, or has been erased. | ||
+ | |- | ||
+ | | <code>403 Forbidden</code> | ||
+ | | <code>ForbiddenOperationException</code> | ||
+ | | | ||
+ | | Invalid token | ||
+ | | An attempt to validate an access token obtained from the <code>/authenticate</code> endpoint that has expired or become invalid. | ||
+ | |- | ||
+ | | <code>429 Too Many Requests</code> | ||
+ | | <code>ForbiddenOperationException</code> | ||
+ | | | ||
+ | | Invalid token. | ||
+ | | An attempt to validate an access token obtained from the <code>/authenticate</code> endpoint that has expired or become invalid while under rate-limiting conditions. | ||
+ | |} | ||
+ | |||
+ | == Authenticate == | ||
+ | |||
+ | Authenticates a user using their password. | ||
+ | |||
+ | === Endpoint === | ||
+ | |||
+ | /authenticate | ||
+ | |||
+ | === Payload === | ||
+ | |||
+ | <syntaxhighlight lang="javascript"> | ||
+ | { | ||
+ | "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 | ||
+ | "requestUser": true // optional; default: false; true adds the user object to the response | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | The <code>clientToken</code> should be a randomly generated identifier and must be identical for each request. The vanilla launcher generates a random (version 4) UUID on first run and saves it, reusing it for every subsequent 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() <code>UUID.toString()</code>] 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"> | ||
+ | { | ||
+ | "user": { | ||
+ | "username": "user@email.example", // will be account username for legacy accounts | ||
+ | "properties": [ | ||
+ | { | ||
+ | "name": "preferredLanguage", | ||
+ | "value": "en-us" | ||
+ | }, | ||
+ | { | ||
+ | "name": "registrationCountry", | ||
+ | "value": "country" // 2L country (e.g. US) | ||
+ | } | ||
+ | ], | ||
+ | "id": "hexadecimal string" // This is the remoteID for the user | ||
+ | }, | ||
+ | "clientToken": "client identifier", | ||
+ | "accessToken": "random access token", // hexadecimal or JSON-Web-Token (unconfirmed) [The normal accessToken can be found in the payload of the JWT (second by '.' separated part as Base64 encoded JSON object), in key "yggt"] | ||
+ | "availableProfiles": [ | ||
+ | { | ||
+ | "name": "player username", | ||
+ | "id": "hexadecimal string" // UUID of the account | ||
+ | } | ||
+ | ], | ||
+ | "selectedProfile": { | ||
+ | "name": "player username", | ||
+ | "id": "hexadecimal string" // UUID of the account | ||
+ | } | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | '''Note:''' If a user wishes to stay logged in on their 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. 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 <code>selectedProfile</code> field, and the <code>availableProfiles</code> array will be empty. | ||
+ | |||
+ | Some instances in the wild have been observed of Mojang returning a flat <code>null</code> 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 <code>/authenticate</code> 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 <code>Invalid credentials.</code> response. This error clears up a few seconds later. | ||
+ | |||
+ | == Refresh == | ||
+ | |||
+ | Refreshes a valid <code>accessToken</code>. 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 === | ||
+ | <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" | ||
+ | }, | ||
+ | "requestUser": true // optional; default: false; true adds the user object to the response | ||
+ | } | ||
+ | </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" | ||
+ | }, | ||
+ | "user": { // only present if requestUser was true in the request payload | ||
+ | "username": "user@email.example", // email for Mojang accounts or account username for legacy Minecraft accounts | ||
+ | "id": "user identifier", // hexadecimal | ||
+ | "properties": [ | ||
+ | { | ||
+ | "name": "preferredLanguage", // might not be present for all accounts | ||
+ | "value": "en" // Java locale format (https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toString--) | ||
+ | }, | ||
+ | { | ||
+ | "name": "twitch_access_token", // only present if a twitch account is associated (see https://account.mojang.com/me/settings) | ||
+ | "value": "twitch oauth token" // OAuth 2.0 Token; alphanumerical; e.g. https://api.twitch.tv/kraken?oauth_token=[...] | ||
+ | // the Twitch API is documented here: https://github.com/justintv/Twitch-API | ||
+ | } | ||
+ | ] | ||
+ | } | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | == Validate == | ||
+ | |||
+ | Checks if an <code>accessToken</code> 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 <code>/refresh</code> if this returns an error. | ||
+ | |||
+ | Note that an <code>accessToken</code> may be unusable for authentication with a Minecraft server, but still be good enough for <code>/refresh</code>. 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 <code>accessToken</code> 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). | ||
+ | |||
+ | <code>/validate</code> may be called with or without a <code>clientToken</code>. If a <code>clientToken</code> is provided, it should match the one used to obtain the <code>accessToken</code>. The Minecraft Launcher does send a <code>clientToken</code> to <code>/validate</code>. | ||
+ | |||
+ | === Endpoint === | ||
+ | |||
+ | /validate | ||
+ | |||
+ | === Payload === | ||
+ | |||
+ | <syntaxhighlight lang="javascript"> | ||
+ | { | ||
+ | "accessToken": "valid accessToken", | ||
+ | "clientToken": "associated clientToken" // optional, see above | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | === Response === | ||
+ | |||
+ | Returns an empty payload (<code>204 No Content</code>) if successful, an error JSON with status <code>403 Forbidden</code> otherwise. | ||
+ | |||
+ | == 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]] | ||
+ | |||
+ | == Examples == | ||
+ | |||
+ | [https://github.com/iBuyMountainDew/yggdrasil Kotlin] | Full Yggdrasil wrapper in Kotlin. | ||
+ | |||
+ | [https://github.com/Kronos666/mclaunch-util-lib Java] | Legacy full Yggdrasil wrapper in Java. | ||
+ | |||
+ | [[Category:Minecraft Modern]] |
Latest revision as of 18:56, 26 February 2024
With the release of Minecraft 1.6, Mojang introduced a new authentication system called Yggdrasil, which replaced the previous Legacy authentication system. This authentication system is also used in Mojang's other game, Scrolls. According to Mojang, the Yggdrasil authentication system should be adopted by developers for custom login implementation, but they strongly advise against collecting credentials from users. For those utilizing newer Microsoft accounts, there is an alternative authentication scheme available called the Microsoft authentication scheme.
Contents
Requests
The Yggdrasil authentication system requests are made to the following server:
https://authserver.mojang.com
To ensure successful requests, they must adhere to the following guidelines:
- Use a
POST
request method - Include a
Content-Type
header set toapplication/json
- Contain a JSON-encoded dictionary as payload
In the event of a successful request, the server will return:
- A
2XX
HTTP status code to indicate success - An empty payload or a JSON-encoded dictionary as specified in the API documentation
In the case of a failed request, the server will respond with:
- An HTTP status code other than
2XX
to indicate failure - A JSON-encoded dictionary following the format below:
{
"error": "Short description of the error",
"cause": "Cause of the error" // optional
"errorMessage": "Longer description which can be shown to the user",
}
Errors
The following are examples of error scenarios that may occur during the use of the Yggdrasil authentication system:
STATUS | error | cause | errorMessage | NOTES |
---|---|---|---|---|
415 Unsupported Media Type
|
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 | An attempt to send a POST request with incorrect request headers to any endpoint. | |
405 Method Not Allowed
|
Method Not Allowed
|
The method specified in the request is not allowed for the resource identified by the request URI | An attempt to use a request method other than POST to access any of the endpoints.
| |
404 Not Found
|
Not Found
|
The server has not found anything matching the request URI | An attempt to send a request to a non-existent endpoint. | |
410 Gone
|
GoneException
|
Migrated | A successful attempt to sign in using a migrated Mojang account. | |
403 Forbidden
|
ForbiddenOperationException
|
Forbidden | An attempt to sign in using empty or insufficiently short credentials. | |
403 Forbidden
|
ForbiddenOperationException
|
Invalid credentials. Invalid username or password. | Either a successful attempt to sign in using an account with excessive login attempts or an unsuccessful attempt to sign in using a non-existent account. | |
403 Forbidden
|
ForbiddenOperationException
|
Invalid credentials. Legacy account is non-premium account. | An unsuccessful attempt to sign in using a Legacy account without a valid Minecraft purchase. | |
403 Forbidden
|
ForbiddenOperationException
|
UserMigratedException
|
Invalid credentials. Account migrated, use email as username. | An unsuccessful attempt to sign in using a migrated Legacy account. |
403 Forbidden
|
TooManyRequestsException
|
Token does not exist | An attempt to refresh an access token that has been invalidated, no longer exists, or has been erased. | |
403 Forbidden
|
ForbiddenOperationException
|
Invalid token | An attempt to validate an access token obtained from the /authenticate endpoint that has expired or become invalid.
| |
429 Too Many Requests
|
ForbiddenOperationException
|
Invalid token. | An attempt to validate an access token obtained from the /authenticate endpoint that has expired or become invalid while under rate-limiting conditions.
|
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
"requestUser": true // optional; default: false; true adds the user object to the response
}
The clientToken
should be a randomly generated identifier and must be identical for each request. The vanilla launcher generates a random (version 4) UUID on first run and saves it, reusing it for every subsequent 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
{
"user": {
"username": "user@email.example", // will be account username for legacy accounts
"properties": [
{
"name": "preferredLanguage",
"value": "en-us"
},
{
"name": "registrationCountry",
"value": "country" // 2L country (e.g. US)
}
],
"id": "hexadecimal string" // This is the remoteID for the user
},
"clientToken": "client identifier",
"accessToken": "random access token", // hexadecimal or JSON-Web-Token (unconfirmed) [The normal accessToken can be found in the payload of the JWT (second by '.' separated part as Base64 encoded JSON object), in key "yggt"]
"availableProfiles": [
{
"name": "player username",
"id": "hexadecimal string" // UUID of the account
}
],
"selectedProfile": {
"name": "player username",
"id": "hexadecimal string" // UUID of the account
}
}
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"
},
"requestUser": true // optional; default: false; true adds the user object to the response
}
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"
},
"user": { // only present if requestUser was true in the request payload
"username": "user@email.example", // email for Mojang accounts or account username for legacy Minecraft accounts
"id": "user identifier", // hexadecimal
"properties": [
{
"name": "preferredLanguage", // might not be present for all accounts
"value": "en" // Java locale format (https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#toString--)
},
{
"name": "twitch_access_token", // only present if a twitch account is associated (see https://account.mojang.com/me/settings)
"value": "twitch oauth token" // OAuth 2.0 Token; alphanumerical; e.g. https://api.twitch.tv/kraken?oauth_token=[...]
// the Twitch API is documented here: https://github.com/justintv/Twitch-API
}
]
}
}
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.
Joining a Server
See Protocol Encryption#Authentication
Examples
Kotlin | Full Yggdrasil wrapper in Kotlin.
Java | Legacy full Yggdrasil wrapper in Java.