Building a Minecraft Launcher - Authentication

This post uses Minecraft Wiki’s page on Microsoft Authentication seen here, which is licensed under a Creative Commons Attribution-ShareAlike 3.0 license. This page is under the same license. Thus, the blog’s usual license does not apply.

How It Works:

I Created a Postman collection with the following requests if needed.

Step One: Setting up the Azure Application / Getting Microsoft Access Token

1. First, you need to create a Microsoft Azure Account.
2. Then you need to make an Azure Application. Refer to this guide for help.
3. Next, you need to set up an OAuth 2.0 authorization flow where the user will be presented with a login page where it will end in a specified URL. More info here.

Note: Ensure that you include XboxLive.signin in the scope field else you will run into issues.

This guide does not include a tutorial on how to get this token as there are so many different ways of doing it.

You now need permission to use api.minecraftservices.com. To do that, you can use this form. From personal experience, this can take a couple of months if its taking too long, you can follow up the form with this email.

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.

Step Two: Authenticate with Xbox Live

Now that you have your Microsoft access token, we can use that to authenticate with Xbox Live

Remember! You need to have permission api.minecraftservices.com to follow these steps. Doing so without permission will return a 403 error.

Note: Ensure you set Content Type to application/json and Accept to application/json

POST https://user.auth.xboxlive.com/user/authenticate

Parameters: <access_token>: Microsoft Access Token

Post Body:

 {
  "Properties": {
    "AuthMethod": "RPS",
    "SiteName": "user.auth.xboxlive.com",
    "RpsTicket": "d=<access_token>"
  },
  "RelyingParty": "http://auth.xboxlive.com",
  "TokenType": "JWT"
}

Response:

  {
  "IssueInstant": "2020-12-07T19:52:08.4463796Z",
  "NotAfter": "2020-12-21T19:52:08.4463796Z",
  "Token": "token",
  "DisplayClaims": {
    "xui": [
      {
        "uhs": "userhash"
      }
    ]
  }
}

The key items to take note of are:

• token - Referred to as Xbox Live Token from now on
• userhash - Referred to as userhash from now on

Step Three: Obtaining a XSTS Token for Minecraft

 POST https://xsts.auth.xboxlive.com/xsts/authorize

Post Body:

  {
  "Properties": {
    "SandboxId": "RETAIL",
    "UserTokens": [
      "Xbox Live Token"
    ]
  },
  "RelyingParty": "rp://api.minecraftservices.com/",
  "TokenType": "JWT"
}

Response:

 {
  "IssueInstant": "2020-12-07T19:52:09.2345095Z",
  "NotAfter": "2020-12-08T11:52:09.2345095Z",
  "Token": "token",
  "DisplayClaims": {
    "xui": [
      {
        "uhs": "userhash"
      }
    ]
  }
}

The key items to take note of are:

• token - Referred to as XSTS Token from now on
• userhash - Same as the one before

Step Four: Authenticate with Minecraft

POST https://api.minecraftservices.com/authentication/login_with_xbox

Post Body:

{
  "identityToken": "XBL3.0 x=<userhash>;<XSTS Token>"
}

Response:

 {
  "username": "some uuid",
  "roles": [],
  "access_token": "minecraft access token",
  "token_type": "Bearer",
  "expires_in": 86400
}

The key items to take note of are:

• some uuid - This is an auth object. This is not your accounts UUID
• minecraft access token - This is the access token for authenticating sessions with.

Step Five: Checking Game Ownership

From here, we now need to ensure that the user actually owns Minecraft and Get Profile Information for that account.

GET https://api.minecraftservices.com/entitlements/mcstore

You need to add the following header:

Authorization: Bearer {minecraft access token}

Response:

 {
  "items": [
    {
      "name": "product_minecraft",
      "signature": "jwt sig"
    },
    {
      "name": "game_minecraft",
      "signature": "jwt sig"
    }
  ],
  "signature": "jwt sig",
  "keyId": "1"
}

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.

If the user does not own the game, the entitlement array will be empty.

Step Six: Getting Profile Data

GET https://api.minecraftservices.com/minecraft/profile

You need to add the following header:

Authorization: Bearer {minecraft access token}

Response:

 {
  "id" : "986dec87b7ec47ff89ff033fdb95c4b5",
  "name" : "HowDoesAuthWork", 
  "skins" : [ {
    "id" : "6a6e65e5-76dd-4c3c-a625-162924514568",
    "state" : "ACTIVE",
    "url" : "http://textures.minecraft.net/texture/1a4af718455d4aab528e7a61f86fa25e6a369d1768dcb13f7df319a713eb810b",
    "variant" : "CLASSIC",
    "alias" : "STEVE"
  } ],
  "capes" : [ ]
 }

The key items to take not of are:

• id - This is the Account UUID
• name - Your Minecraft Username

What I Built:

CauldronAuthenticator:

With this Information, I created the CauldronAuthentication package this package handles the entire Microsoft Authentication Scheme into one function.

This Function startAuthenticationFlow takes a Microsoft Access Token as a parameter and processes it into the following item:

{
  "profile": {
    "uuid": "Minecraft UUID",
    "username": "Minecraft UUID"
  },
  "xui": "XUI Token",
  "access_token": "Minecraft Access Token",
  "user_id": "User ID"
}

This provides all the necessary information to launch a Minecraft Session.