Difference between revisions of "Authentication"

From wiki.vg
Jump to navigation Jump to search
m (switched to gender neutral pronouns to match rest of wiki)
m (formatting)
Line 1: Line 1:
Minecraft 1.6 introduced a new authentication scheme called Yggdrasil which completely replaces the [[Legacy_Authentication|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[https://twitter.com/KrisJelbring/status/453573406341206016], but credentials should never be collected from users[https://twitter.com/KrisJelbring/status/461390585086361600].
+
Minecraft 1.6 introduced a new authentication scheme called '''Yggdrasil''' which completely replaces the [[Legacy Authentication|previous authentication system]]. Mojang's other game, Scrolls, uses this method of authentication as well. Mojang has said that [https://twitter.com/KrisJelbring/status/453573406341206016 this authentication system should be used by everyone for custom logins], but [https://twitter.com/KrisJelbring/status/461390585086361600 credentials should never be collected from users].
  
 
== Request format ==
 
== Request format ==
Line 5: Line 5:
 
All requests to Yggdrasil are made to the following server:
 
All requests to Yggdrasil are made to the following server:
  
  https://authserver.mojang.com
+
https://authserver.mojang.com
  
 
Further, they are expected to fulfill the following rules:
 
Further, they are expected to fulfill the following rules:
Line 11: Line 11:
 
* Are <code>POST</code> requests
 
* Are <code>POST</code> requests
 
* Have the <code>Content-Type</code> header set to <code>application/json</code>
 
* Have the <code>Content-Type</code> header set to <code>application/json</code>
* Contain a [http://json.org JSON]-encoded dictionary as payload
+
* Contain a [[wikipedia:JSON|JSON]]-encoded dictionary as payload
  
 
If a request was successful the server will respond with:
 
If a request was successful the server will respond with:
  
 
* Status code <code>200</code>
 
* Status code <code>200</code>
* A [http://json.org JSON]-encoded dictionary according to the specifications below
+
* A [[wikipedia:JSON|JSON]]-encoded dictionary according to the specifications below
  
 
If however a request fails, the server will respond with:
 
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]
+
* An appropriate, non-200 [[wikipedia:List of HTTP status codes|HTTP status code]]
* A [http://json.org JSON]-encoded dictionary following this format:
+
* A [[wikipedia:JSON|JSON]]-encoded dictionary following this format:
 +
 
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "error": "Short description of the error",
+
    "error": "Short description of the error",
  "errorMessage": "Longer description which can be shown to the user",
+
    "errorMessage": "Longer description which can be shown to the user",
  "cause": "Cause of the error"       // optional
+
    "cause": "Cause of the error" // optional
 
}
 
}
 
</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"
|-
+
|-
! Error
+
! Error
! Cause
+
! Cause
! Error message
+
! Error message
! Notes
+
! Notes
|-
+
|-
| <code>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
+
| 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.
+
| Something other than a POST request was received.
|-
+
|-
| <code>Not Found</code>
+
| <code>Not Found</code>
|
+
|
| The server has not found anything matching the request URI
+
| The server has not found anything matching the request URI
| Non-existing endpoint was called.
+
| Non-existing endpoint was called.
|-
+
|-
| <code>ForbiddenOperationException</code>
+
| <code>ForbiddenOperationException</code>
| <code>UserMigratedException</code>
+
| <code>UserMigratedException</code>
| Invalid credentials. Account migrated, use e-mail as username.
+
| Invalid credentials. Account migrated, use e-mail as username.
|  
+
|  
|-
+
|-
| <code>ForbiddenOperationException</code>
+
| <code>ForbiddenOperationException</code>
|  
+
|  
| Invalid credentials. Invalid username or password.
+
| Invalid credentials. Invalid username or password.
|  
+
|  
|-
+
|-
| <code>ForbiddenOperationException</code>
+
| <code>ForbiddenOperationException</code>
|  
+
|  
| Invalid token.
+
| Invalid token.
| <code>accessToken</code> was invalid.
+
| <code>accessToken</code> was invalid.
|-
+
|-
| <code>IllegalArgumentException</code>
+
| <code>IllegalArgumentException</code>
|  
+
|  
| Access token already has a profile assigned.
+
| Access token already has a profile assigned.
| Selecting profiles isn't implemented yet.
+
| Selecting profiles isn't implemented yet.
|-
+
|-
| <code>IllegalArgumentException</code>
+
| <code>IllegalArgumentException</code>
|  
+
|  
| credentials can not be null.
+
| credentials can not be null.
| Username/password was not submitted.
+
| Username/password was not submitted.
|-
+
|-
| <code>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
+
| 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
+
| Data was not submitted as application/json
|}
+
|}
  
 
== Authenticate ==
 
== Authenticate ==
Line 85: Line 88:
  
 
=== Endpoint ===
 
=== Endpoint ===
  /authenticate
+
 
 +
/authenticate
  
 
=== Payload ===
 
=== Payload ===
 +
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "agent": {                             // defaults to Minecraft
+
    "agent": {                             // defaults to Minecraft
    "name": "Minecraft",                 // For Mojang's other game Scrolls, "Scrolls" should be used
+
        "name": "Minecraft",               // For Mojang's other game Scrolls, "Scrolls" should be used
    "version": 1                         // This number might be increased
+
        "version": 1                       // This number might be increased
                                        // by the vanilla client in the future
+
                                            // by the vanilla client in the future
  },
+
    },
  "username": "mojang account name",     // Can be an email address or player name for
+
    "username": "mojang account name",     // Can be an email address or player name for
                                        // unmigrated accounts
+
                                            // unmigrated accounts
  "password": "mojang account password",
+
    "password": "mojang account password",
  "clientToken": "client identifier"     // optional
+
    "clientToken": "client identifier"     // optional
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
The <code>clientToken</code> should be a randomly generated identifier and must be 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() <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.
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">
 
{
 
{
  "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": [                // only present if the agent field was received
+
    "availableProfiles": [                // only present if the agent field was received
    {
+
        {
      "id": "profile identifier",       // hexadecimal
+
            "id": "profile identifier",   // hexadecimal
      "name": "player name",
+
            "name": "player name",
      "legacy": true or false         // In practice, this field only appears in the response if true. Default to false.
+
            "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
 
     }
 
     }
  ],
 
  "selectedProfile": {                  // only present if the agent field was received
 
    "id": "profile identifier",
 
    "name": "player name",
 
    "legacy": true or false
 
  }
 
 
}
 
}
 
</syntaxhighlight>
 
</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.
 
'''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 "selectedProfile" field, and the "availableProfiles" array will be empty.
+
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 "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.
+
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.
  
 
== Refresh ==
 
== Refresh ==
Line 135: Line 141:
  
 
=== Endpoint ===
 
=== Endpoint ===
  /refresh
+
 
 +
/refresh
  
 
=== Payload ===
 
=== Payload ===
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "accessToken": "valid accessToken",
+
    "accessToken": "valid accessToken",
  "clientToken": "client identifier"     // This needs to be identical to the one used
+
    "clientToken": "client identifier"// This needs to be identical to the one used
 
                                         // to obtain the accessToken in the first place
 
                                         // to obtain the accessToken in the first place
  "selectedProfile": {                   // optional; sending it will result in an error
+
    "selectedProfile": {                 // optional; sending it will result in an error
    "id": "profile identifier",         // hexadecimal
+
        "id": "profile identifier",     // hexadecimal
    "name": "player name"
+
        "name": "player name"
  }
+
    }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 153: Line 160:
  
 
=== Response ===
 
=== Response ===
 +
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "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
  "selectedProfile": {
+
    "selectedProfile": {
    "id": "profile identifier",         // hexadecimal
+
        "id": "profile identifier",       // hexadecimal
    "name": "player name"
+
        "name": "player name"
  }
+
    }
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 166: Line 174:
 
== Validate ==
 
== Validate ==
  
Checks if an <code>accessToken</code> is a valid session token with a currently-active session.  Note: this method will not respond successfully to all currently-logged-in sessions, just the most recently-logged-in for each user.  It is intended to be used by servers to validate that a user should be connecting (and reject users who have logged in elsewhere since starting Minecraft), NOT to auth that a particular session token is valid for authentication purposes. To authenticate a user by session token, use the refresh verb and catch resulting errors.
+
Checks if an <code>accessToken</code> is a valid session token with a currently-active session.  Note: this method will not respond successfully to all currently-logged-in sessions, just the most recently-logged-in for each user.  It is intended to be used by servers to validate that a user should be connecting (and reject users who have logged in elsewhere since starting Minecraft), ''not'' to auth that a particular session token is valid for authentication purposes. To authenticate a user by session token, use the refresh verb and catch resulting errors.
  
 
=== Endpoint ===
 
=== Endpoint ===
  /validate
+
 
 +
/validate
  
 
=== Payload ===
 
=== Payload ===
 +
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "accessToken": "valid accessToken",
+
    "accessToken": "valid accessToken"
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
=== Response ===
 
=== Response ===
 +
 
Returns an empty payload if successful.
 
Returns an empty payload if successful.
  
Line 186: Line 197:
  
 
=== Endpoint ===
 
=== Endpoint ===
  /signout
+
 
 +
/signout
  
 
=== Payload ===
 
=== Payload ===
 +
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "username": "mojang account name",
+
    "username": "mojang account name",
  "password": "mojang account password",
+
    "password": "mojang account password"
 
}
 
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
=== Response ===
 
=== Response ===
 +
 
Returns an empty payload if successful.
 
Returns an empty payload if successful.
  
Line 204: Line 218:
  
 
=== Endpoint ===
 
=== Endpoint ===
  /invalidate
+
 
 +
/invalidate
  
 
=== Payload ===
 
=== Payload ===
 +
 
<syntaxhighlight lang="javascript">
 
<syntaxhighlight lang="javascript">
 
{
 
{
  "accessToken": "valid accessToken",
+
    "accessToken": "valid accessToken",
  "clientToken": "client identifier"     // This needs to be identical to the one used
+
    "clientToken": "client identifier"   // This needs to be identical to the one used
 
                                         // to obtain the accessToken in the first place
 
                                         // to obtain the accessToken in the first place
 
}
 
}
Line 216: Line 232:
  
 
=== Response ===
 
=== Response ===
 +
 
Returns an empty payload if successful.
 
Returns an empty payload if successful.
  
 
== Joining a Server ==
 
== Joining a Server ==
  
See [[Protocol Encryption#Authentication|Protocol Encryption]]
+
See [[Protocol Encryption#Authentication]]
 
 
  
 
[[Category:Protocol Details]]
 
[[Category:Protocol Details]]
 
[[Category:Minecraft Modern]]
 
[[Category:Minecraft Modern]]

Revision as of 23:30, 9 July 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.

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.
IllegalArgumentException credentials can not be 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 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",
            "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.

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 a valid session token with a currently-active session. Note: this method will not respond successfully to all currently-logged-in sessions, just the most recently-logged-in for each user. It is intended to be used by servers to validate that a user should be connecting (and reject users who have logged in elsewhere since starting Minecraft), not to auth that a particular session token is valid for authentication purposes. To authenticate a user by session token, use the refresh verb and catch resulting errors.

Endpoint

/validate

Payload

{
    "accessToken": "valid accessToken"
}

Response

Returns an empty payload if successful.

Signout

Invalidates accessTokens 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 accessTokens 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