Auth
This package implements the full Microsoft Authentication flow for Minecraft: Java Edition, allowing clients to obtain valid Minecraft access tokens for joining online-mode servers.
Overview
Since Minecraft 1.16, Mojang accounts have been migrated to Microsoft accounts. Authentication now requires a multi-step process involving Microsoft OAuth2, Xbox Live, XSTS, and Minecraft services.
Authentication Flow
┌────────────────────────────────────────────────────────────────────────────┐
│ Microsoft Authentication │
└────────────────────────────────────────────────────────────────────────────┘
┌─────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ User │ │ Microsoft │ │ Xbox Live │ │ XSTS │
│ Browser │ │ OAuth2 │ │ (XBL) │ │ Service │
└────┬────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │ │
│ Login Page │ │ │
│◄────────────────│ │ │
│ │ │ │
│ Auth Code │ │ │
│────────────────►│ │ │
│ │ │ │
│ ┌─────┴─────┐ │ │
│ │ Exchange │ │ │
│ │ Code │ │ │
│ └─────┬─────┘ │ │
│ │ │ │
│ │ MS Access Token │ │
│ │───────────────────►│ │
│ │ │ │
│ │ ┌─────┴─────┐ │
│ │ │ XBL │ │
│ │ │ Auth │ │
│ │ └─────┬─────┘ │
│ │ │ │
│ │ │ XBL Token │
│ │ │───────────────────►│
│ │ │ │
│ │ │ ┌─────┴─────┐
│ │ │ │ XSTS │
│ │ │ │ Authorize │
│ │ │ └─────┬─────┘
│ │ │ │
│ │ │ ▼
│ │ │ XSTS Token
│ │ │ │
└─────────────────┴────────────────────┴────────────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ Minecraft Authentication │
└──────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Minecraft │ │ Entitlements │ │ Profile │
│ Service │ │ Check │ │ Fetch │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
│ │ │
│ XSTS Token │ │
│◄───────────────────┘ │
│ │ │
┌─────┴─────┐ │ │
│ Login │ │ │
│ with Xbox │ │ │
└─────┬─────┘ │ │
│ │ │
│ MC Access Token │ │
│───────────────────►│ │
│ │ │
│ ┌─────┴─────┐ │
│ │ Verify │ │
│ │ Ownership │ │
│ └─────┬─────┘ │
│ │ │
│ │───────────────────►│
│ │ │
│ │ ┌─────┴─────┐
│ │ │ Get │
│ │ │ Profile │
│ │ └─────┬─────┘
│ │ │
│ │ ▼
│ │ UUID + Username
│ │ │
└────────────────────┴────────────────────┘
Authentication Steps
- Microsoft OAuth2 - User logs in via browser, app receives authorization code
- Token Exchange - Code exchanged for Microsoft access token and refresh token
- Xbox Live (XBL) - Microsoft token exchanged for Xbox Live token
- XSTS Authorization - XBL token authorized for Minecraft services
- Minecraft Login - XSTS token exchanged for Minecraft access token
- Entitlement Check - Verify the account owns Minecraft
- Profile Fetch - Retrieve player UUID, username and access token to join servers
Usage
Basic Login (Interactive)
client := auth.NewClient(auth.Config{
ClientID: "your-azure-app-client-id",
})
ctx := context.Background()
loginData, err := client.Login(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Logged in as %s (UUID: %s)\n", loginData.Username, loginData.UUID)
// use loginData.AccessToken to join servers
Login with Session Caching
The Login() method automatically handles full session caching, including the Minecraft access token:
- Check cached session - If a valid session exists (access token not expired), returns immediately with zero API calls
- Refresh if expired - If session expired but refresh token exists, refreshes through the full auth chain
- Interactive fallback - If no cache or refresh fails, opens browser for interactive login
- Save session - Caches the full session (access token, refresh token, UUID, username, expiry) for future use
The Minecraft access token is valid for 24 hours, so rapid start/stop cycles won't trigger re-authentication.
client := auth.NewClient(auth.Config{
ClientID: "your-azure-app-client-id",
Username: "PlayerName", // specify which cached account to use
})
// first call: may need interactive login or token refresh
loginData, err := client.Login(ctx)
// subsequent calls within 24 hours: returns immediately from cache
loginData, err = client.Login(ctx)
Login with Refresh Token (Non-Interactive)
If you already have a refresh token:
client := auth.NewClient(auth.Config{
ClientID: "your-azure-app-client-id",
})
loginData, err := client.LoginWithRefreshToken(ctx, refreshToken)
if err != nil {
// token expired or invalid, need interactive login
}
Custom Token Storage
By default, tokens are stored in ~/.mclib/credentials_cache.json. You can customize this:
// custom file path
store, err := auth.NewFileTokenStore(filepath.Join(os.Getenv("HOME"), "my_credentials_cache.json"))
if err != nil {
log.Fatal(err)
}
client := auth.NewClient(auth.Config{
ClientID: "your-client-id",
TokenStore: store,
})
// in-memory only (no persistence)
client := auth.NewClient(auth.Config{
ClientID: "your-client-id",
TokenStore: auth.NewMemoryTokenStore(),
})
// custom implementation (e.g. a database), implementing
// SaveSession(*auth.LoginData) and LoadSession(username)
client := auth.NewClient(auth.Config{
ClientID: "your-client-id",
TokenStore: myCustomStore,
})
If the browser cannot be opened (headless environments), the sign-in URL is printed to stderr and the local callback server keeps waiting.
Fetching Mojang Certificates
For chat message signing (1.19+), you need Mojang-issued certificates. To do this, you need to have the access token of the account you want to sign messages for.
certData, err := authClient.FetchMojangCertificate(ctx, loginData.AccessToken)
if err != nil {
log.Fatal(err)
}
// certData.PrivateKey - RSA private key for signing
// certData.PublicKeyBytes - DER-encoded public key
// certData.SignatureBytes - raw bytes of Mojang's signature of your public key
// certData.ExpiryTime - when the certificate expires
Configuration
| Field |
Description |
Default |
ClientID |
Azure AD application client ID |
Required |
RedirectPort |
Local loopback port for OAuth callback |
Free port chosen by the OS |
Scopes |
OAuth scopes to request |
["XboxLive.signin", "offline_access"] |
HTTPClient |
Custom HTTP client |
20s timeout client |
TokenStore |
Session storage (NewFileTokenStore, NewMemoryTokenStore or custom) |
File store at ~/.mclib/credentials_cache.json |
Username |
Account username for caching |
From login response |
API Endpoints Used
| Service |
Endpoint |
Purpose |
| Microsoft |
https://login.live.com/oauth20_authorize.srf |
OAuth authorization |
| Microsoft |
https://login.live.com/oauth20_token.srf |
Token exchange/refresh |
| Xbox Live |
https://user.auth.xboxlive.com/user/authenticate |
XBL authentication |
| XSTS |
https://xsts.auth.xboxlive.com/xsts/authorize |
XSTS authorization |
| Minecraft |
https://api.minecraftservices.com/authentication/login_with_xbox |
MC token |
| Minecraft |
https://api.minecraftservices.com/entitlements/mcstore |
Ownership check |
| Minecraft |
https://api.minecraftservices.com/minecraft/profile |
Profile data |
| Minecraft |
https://api.minecraftservices.com/player/certificates |
Chat signing certs |
Creating an Azure Application
To use this package, you need an Azure AD application:
- Go to Azure Portal
- Navigate to Azure Active Directory → App registrations
- Click "New registration"
- Set redirect URI to
http://127.0.0.1 (Mobile and desktop applications)
- Under "API permissions", add
XboxLive.signin and offline_access
- Copy the "Application (client) ID" - this is your
ClientID
Session Caching
The auth package caches full sessions to disk, including:
- Access token - The Minecraft JWT used to join servers
- Refresh token - Long-lived token for obtaining new access tokens
- UUID - Player's unique identifier (
ns.UUID, stored as a hyphenated string; older dashless entries still load)
- Username - Player's display name
- Expiry time - When the access token expires (24 hours from issuance)
Sessions are automatically migrated from the old format (refresh token only) to the new format on first load.
Security Notes
- Sessions are stored with
0600 permissions (owner read/write only)
- Tokens are saved atomically using a unique temp file + rename
- The OAuth callback only accepts requests carrying the random
state sent with the authorization URL
- Access tokens expire after 24 hours; refresh tokens are long-lived (90+ days)
- A 5-minute buffer is used when checking expiry to avoid edge cases
- The
offline_access scope is required for refresh token functionality
References