Microsoft Authentication Scheme

Revision as of 15:26, 15 June 2024 by SSSSSteven (talk | contribs) (Mojang deleted errorType and developerMessage in "Getting the profile" error response)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Minecraft is moving to Microsoft accounts. Starting December 2020, all new Accounts already use the new system, old accounts will be migrated later, see this blog post

There are multiple steps and different tokens required, but in the end, you get a normal Minecraft token back. Launching the game itself hasn't changed.

Microsoft OAuth2 Flow

Prior to any of these steps, you will first need to obtain an OAuth 2.0 client ID by creating a Microsoft Azure application. You will not need to obtain a client secret.

You can then use the OAuth2 authorization code flow to obtain an access token. You'll need to present the user with a login page that, once completed, will redirect to a specified URL with the token in the query parameters. In non-web applications this typically involves spinning up a temporary HTTP server to handle the redirect. If you'd rather not do that, consider using the (slightly less automatic) device code flow instead.

In any case, you'll need to include XboxLive.signin in the scope parameter of the authorization request; otherwise the next endpoint will complain, and not in a helpful way.

According to this support Article, new created Azure Apps must apply for the Permission to use the Minecraft API using this form. If your App don't have the Permission will return a 403.

Note: You must use the consumers AAD tenant to sign in with the XboxLive.signin scope. Using an Azure AD tenant ID or the common scope will just give errors. This also means you cannot sign in with users that are in the AAD tenant, only with consumer Microsoft accounts.

Authenticate with Xbox Live

Now that we are authenticated with Microsoft, we can authenticate with Xbox Live.

To do that, we send

 1  POST
 2  {
 3     "Properties": {
 4         "AuthMethod": "RPS",
 5         "SiteName": "",
 6         "RpsTicket": "d=<access token>" // your access token from the previous step here
 7     },
 8     "RelyingParty": "",
 9     "TokenType": "JWT"
10  }

Again, it will complain if you don't set Content-Type: application/json and Accept: application/json. It will also complain if your SSL implementation does not support SSL renegotiations.

The response will look like this:

 1  {
 2    "IssueInstant":"2020-12-07T19:52:08.4463796Z",
 3    "NotAfter":"2020-12-21T19:52:08.4463796Z",
 4    "Token":"token", // save this, this is your xbl token
 5    "DisplayClaims":{
 6       "xui":[
 7          {
 8             "uhs":"userhash" // save this
 9          }
10       ]
11    }
12  }

Obtain XSTS token for Minecraft

Now that we are authenticated with XBL, we need to get a XSTS token, we can use to login to Minecraft.

 1  POST
 2  {
 3     "Properties": {
 4         "SandboxId": "RETAIL",
 5         "UserTokens": [
 6             "xbl_token" // from above
 7         ]
 8     },
 9     "RelyingParty": "rp://",
10     "TokenType": "JWT"
11  }

Again, set content type and accept to json and ensure SSL renegotiation is supported by your client.

Note: When trying to get the XSTS token for the bedrock realms API, you need to change the following:

"RelyingParty": ""

also you can stop at this point, as the bedrock realms API uses the XSTS token directly instead of a seperate auth scheme.

Response will look like this:

 1  {
 2    "IssueInstant":"2020-12-07T19:52:09.2345095Z",
 3    "NotAfter":"2020-12-08T11:52:09.2345095Z",
 4    "Token":"token", // save this, this is your xsts token
 5    "DisplayClaims":{
 6       "xui":[
 7          {
 8             "uhs":"userhash" // same as last request
 9          }
10       ]
11    }
12 }

The endpoint can return a 401 error with the below response:

1  {
2     "Identity":"0",
3     "XErr":2148916238,
4     "Message":"",
5     "Redirect":""
6  }

The Redirect parameter usually will not resolve or go anywhere in a browser, likely they're targeting Xbox consoles.

Noted XErr codes and their meanings:

  • 2148916233: The account doesn't have an Xbox account. Once they sign up for one (or login through to create one) then they can proceed with the login. This shouldn't happen with accounts that have purchased Minecraft with a Microsoft account, as they would've already gone through that Xbox signup process.
  • 2148916235: The account is from a country where Xbox Live is not available/banned
  • 2148916236: The account needs adult verification on Xbox page. (South Korea)
  • 2148916237: The account needs adult verification on Xbox page. (South Korea)
  • 2148916238: The account is a child (under 18) and cannot proceed unless the account is added to a Family by an adult. This only seems to occur when using a custom Microsoft Azure application. When using the Minecraft launchers client id, this doesn't trigger.

Authenticate with Minecraft

Now we can finally start talking to Minecraft. The XSTS token from the last request allows us to authenticate with Minecraft using

2  {
3     "identityToken": "XBL3.0 x=<userhash>;<xsts_token>"
4  }


1  {
2   "username" : "some uuid", // this is not the uuid of the account
3   "roles" : [ ],
4   "access_token" : "minecraft access token", // jwt, your good old minecraft access token
5   "token_type" : "Bearer",
6   "expires_in" : 86400
7  }

This access token allows us to launch the game, but, we haven't actually checked if the account owns the game. Everything until here works with a normal Microsoft account!

Checking Game Ownership

So let's use our mc access token to check if a product licence is attached to the account.


The access token goes into the auth header: Authorization: Bearer <Minecraft Access Token>. (Keep in mind that Bearer is actually the prefix you must include!)

If the account owns the game, the response will look like this:

 1  {
 2   "items" : [ {
 3     "name" : "product_minecraft",
 4     "signature" : "jwt sig"
 5   }, {
 6     "name" : "game_minecraft",
 7     "signature" : "jwt sig"
 8   } ],
 9   "signature" : "jwt sig",
10   "keyId" : "1"
11  }

The first jwts contain the values:

1  {
2   "typ": "JWT",
3   "alg": "RS256",
4   "kid": "1"
5  }.{
6   "signerId": "2535416586892404",
7   "name": "product_minecraft"
8  }.[Signature]

the last jwt looks like this decoded:

 1  {
 2   "typ": "JWT",
 3   "alg": "RS256",
 4   "kid": "1"
 5  }.{
 6   "entitlements": [
 7     {
 8       "name": "product_minecraft"
 9     },
10     {
11       "name": "game_minecraft"
12     }
13   ],
14   "signerId": "2535416586892404"
15  }.[Signature]

If the account doesn't own the game, the items array will be empty.

Note that Xbox Game Pass users don't technically own the game, and therefore will not show any ownership here, but will indeed have a Minecraft profile attached to their account.

Note that the signature should always be checked with the public key from Mojang to verify that it is a legitimate response from the official servers:

-----END PUBLIC KEY-----

See the JWT standard[1] for more details.

In case the public key ever changes, it can be extracted from the launcher library:

strings ~/.minecraft/launcher/ > launcher-strings.txt

The created file launcher-strings.txt will include 2 strings which begin with -----BEGIN PUBLIC KEY----- and end with -----END PUBLIC KEY-----. The first key seems to be the one used for the JWT tokens, use of the second key is unknown.

Getting the profile

Now that we know that the account owns the game, we can get their profile in order to fetch the UUID:


Again, the access token goes into the auth header: Authorization: Bearer token

The response will look like this, if the account owns the game:

 1  {
 2   "id" : "986dec87b7ec47ff89ff033fdb95c4b5", // the real uuid of the account, woo
 3   "name" : "HowDoesAuthWork", // the mc user name of the account
 4   "skins" : [ {
 5     "id" : "6a6e65e5-76dd-4c3c-a625-162924514568",
 6     "state" : "ACTIVE",
 7     "url" : "",
 8     "variant" : "CLASSIC",
 9     "alias" : "STEVE"
10   } ],
11   "capes" : [ ]
12  }

Else it will look like this:

1  {
2   "path" : "/minecraft/profile",
3   "error" : "NOT_FOUND",
4   "errorMessage" : "The server has not found anything matching the request URI"
5  }

Note that Xbox Game Pass users who haven't logged into the new Minecraft Launcher at least once will not return a profile, and will need to login once after activating Xbox Game Pass to setup their Minecraft username.

You should now have all necessary data (the mc access token, the username and the uuid) to launch the game. Well done!

Sample Implementations Authentication like the launcher does (i.e. code flow) + refresh token request.

A fully working kotlin implementation can be found [2] here using device tokens.

A fully working cli wrapper in Java using device tokens here

A rough sample implementation in Java (using javafx and its webview) here.

A fully working Java library supporting 4 login flows can be found here.

An implementation in Go here.

An implementation in JS can be found here and one using JS/TS here

An implementation in Python can be found here

An implementation in Rust can be found here.

A Kotlin library (JVM + JS) can be found here.

A C# library using webview and MSAL.NET can be found here.

A Rust library can be found here.

A PHP library can be found here.