Editing Microsoft Authentication Scheme

Minecraft is moving to Microsoft accounts. Starting December 2020, all new Accounts already use the new system, old accounts will be migrated later, see [https://www.minecraft.net/en-us/article/java-edition-moving-house 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 OAuth Flow ==
[[File:minecraft_login.png|frame|Example of the login page]]

Prior to any of these steps, you will first need to obtain an [https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow OAuth 2.0] Client ID & secret by creating a [https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app  Microsoft Azure application].

In the first step, we are logging into the Microsoft account. This has to be done in a browser/webview!

The URL generated, either manually, or through an OAuth2 library, would look something like this:

 https://login.live.com/oauth20_authorize.srf
  ?client_id=<your Azure client ID>
  &response_type=code
  &redirect_uri=<your redirect uri>
  &scope=XboxLive.signin
  &state=<optional; used to prevent CSRF & restoring previous application states>

<i>Note: You may also use the Azure Active Directory endpoints which would look like https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize but this just redirects to the live.com URL.</i>

The user will be prompted to enter a username (E-Mail, Skype ID, Phone number, whatever) and their password. If those are valid, the user will be redirected. The user doesn't need to own MC, that check comes way later!

The redirect will look something like this
 https://<your redirect URL>?code=codegoeshere&state=<optional; only if provided>

You have to extract the code param, it's your Microsoft Authorization Code.

== Authorization Code -> Authorization Token ==

The next step is to get an access token from the auth code. This isn't done in the browser for security reasons.

<i>This exchange should be done on the server-side as it requires the use of your client secret which, as the name implies, should be kept secret.</i>

 POST https://login.live.com/oauth20_token.srf
Content:

<syntaxhighlight lang="java" line='line'>
 Map<Object, Object> data = Map.of(
    "client_id", "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
    "code", authcode, // the code from step 1
    "grant_type", "authorization_code",
    "redirect_uri", "YOUR_REDIRECT_URI",
 );
</syntaxhighlight>

Don't forget to set <code>Content-Type: application/x-www-form-urlencoded</code>

The response will look like this:

<syntaxhighlight lang="json" line='line'>
 {
   "token_type":"bearer",
   "expires_in":86400,
   "scope":"XboxLive.signin",
   "access_token":"token here",
   "refresh_token":"M.R3_BAY.token here",
   "user_id":"889ed4a3d844f672",
   "foci":"1"
 }
</syntaxhighlight>

We care about the access_token here. (TODO: check what we can do with the refresh token)


An example of this exchange, in Go, can be found here:
https://gist.github.com/rbrick/be8ed86864fc5d77aa6c979053cfc892#file-msa-go-L35-L49

== Authenticate with XBL ==

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

To do that, we send

<syntaxhighlight lang="json" line='line'>
 POST https://user.auth.xboxlive.com/user/authenticate
 {
    "Properties": {
        "AuthMethod": "RPS",
        "SiteName": "user.auth.xboxlive.com",
        "RpsTicket": "access_token" // your access token from step 2 here
    },
    "RelyingParty": "http://auth.xboxlive.com",
    "TokenType": "JWT"
 }
</syntaxhighlight>

Again, it will complain if you don't set <code>Content-Type: application/json</code> and <code>Accept: application/json</code>

The response will look like this:

<syntaxhighlight lang="json" line='line'>
 {
   "IssueInstant":"2020-12-07T19:52:08.4463796Z",
   "NotAfter":"2020-12-21T19:52:08.4463796Z",
   "Token":"token", // save this, this is your xbl token
   "DisplayClaims":{
      "xui":[
         {
            "uhs":"uhs" // save this
         }
      ]
   }
 }
</syntaxhighlight>

We need to save token and uhs. I have no idea what uhs stands for. (TODO: find out)

== Authenticate with XSTS ==

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

<syntaxhighlight lang="json" line='line'>
 POST https://xsts.auth.xboxlive.com/xsts/authorize
 {
    "Properties": {
        "SandboxId": "RETAIL",
        "UserTokens": [
            "xbl_token" // from above
        ]
    },
    "RelyingParty": "rp://api.minecraftservices.com/",
    "TokenType": "JWT"
 }
</syntaxhighlight>

Again, set content type and accept to json.

Response will look like this:

<syntaxhighlight lang="json" line='line'>
 {
   "IssueInstant":"2020-12-07T19:52:09.2345095Z",
   "NotAfter":"2020-12-08T11:52:09.2345095Z",
   "Token":"token", // save this, this is your xsts token
   "DisplayClaims":{
      "xui":[
         {
            "uhs":"" // same as last request
         }
      ]
   }
}
</syntaxhighlight>

== Authenticate with Minecraft ==

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

<syntaxhighlight lang="json" line='line'>
 POST https://api.minecraftservices.com/authentication/login_with_xbox
 {
    "identityToken": "XBL3.0 x=<uhs>;<xsts_token>"
 }
</syntaxhighlight>

Response:
<syntaxhighlight lang="json" line='line'>
 {
  "username" : "some uuid", // this is not the uuid of the account
  "roles" : [ ],
  "access_token" : "minecraft access token", // jwt, your good old minecraft access token
  "token_type" : "Bearer",
  "expires_in" : 86400
 }
</syntaxhighlight>

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.
 GET https://api.minecraftservices.com/entitlements/mcstore

The access token goes into the auth header: <code>Authorization: Bearer token</code>

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

<syntaxhighlight lang="json" line='line'>
 {
  "items" : [ {
    "name" : "product_minecraft",
    "signature" : "jwt sig"
  }, {
    "name" : "game_minecraft",
    "signature" : "jwt sig"
  } ],
  "signature" : "jwt sig",
  "keyId" : "1"
 }
</syntaxhighlight>

The first jwts contain the values:
<syntaxhighlight lang="json" line='line'>
 {
  "typ": "JWT",
  "alg": "RS256",
  "kid": "1"
 }.{
  "signerId": "2535416586892404",
  "name": "product_minecraft"
 }.[Signature]
</syntaxhighlight>

the last jwt looks like this decoded:

<syntaxhighlight lang="json" line='line'>
 {
  "typ": "JWT",
  "alg": "RS256",
  "kid": "1"
 }.{
  "entitlements": [
    {
      "name": "product_minecraft"
    },
    {
      "name": "game_minecraft"
    }
  ],
  "signerId": "2535416586892404"
 }.[Signature]
</syntaxhighlight>

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

== Get the profile ==

Now that we know that the account owns the game, lets get his profile so we get uuid:
 GET https://api.minecraftservices.com/minecraft/profile

Again, the access token goes into the auth header: <code>Authorization: Bearer token</code>

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

<syntaxhighlight lang="json" line='line'>
 {
  "id" : "986dec87b7ec47ff89ff033fdb95c4b5", // the real uuid of the account, woo
  "name" : "HowDoesAuthWork", // the mc user name of the account
  "skins" : [ {
    "id" : "6a6e65e5-76dd-4c3c-a625-162924514568",
    "state" : "ACTIVE",
    "url" : "http://textures.minecraft.net/texture/1a4af718455d4aab528e7a61f86fa25e6a369d1768dcb13f7df319a713eb810b",
    "variant" : "CLASSIC",
    "alias" : "STEVE"
  } ],
  "capes" : [ ]
 }
</syntaxhighlight>

Else it will look like this:

<syntaxhighlight lang="json" line='line'>
 {
  "path" : "/minecraft/profile",
  "errorType" : "NOT_FOUND",
  "error" : "NOT_FOUND",
  "errorMessage" : "The server has not found anything matching the request URI",
  "developerMessage" : "The server has not found anything matching the request URI"
 }
</syntaxhighlight>

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

== Sample Implementations ==
There is a rough sample implementation in Java (using javafx and its webview) [https://github.com/MiniDigger/MiniLauncher/blob/master/launcher/src/main/java/me/minidigger/minecraftlauncher/launcher/gui/MsaFragmentController.java here].