Crate mc_headless_auth 

MC-HA

Minecraft Headless Authenticator for 1.21.2+

A simple way to authenticate a minecraft account via joining a server & syncing a token.

This library offloads the authentication process to the launcher + client.
Only using a barebones Minecraft server to verify the authentication and retreive the player details.

Usage

use mc_headless_auth::{Server, ServerConfig};

fn main() {
    let server = Server::start(ServerConfig::default());

    let token = String::from("...");
    let player = server.verify(&token.trim().to_uppercase());
    assert!(player.is_some());
}

A typical use of this would be to have a user already be logged into your service.
Then while logged in, you ask them to join the Minecraft server.
And respond back with the token given in Minecraft, on the site.
You then check if the token is real and retreive the Minecraft user.
With this information you have now linked your users account with their Minecraft account.

This process is way simpler than for example using Microsoft OAuth2.
The only downside is requiring that the user opens a relatively modern Minecraft client and joins a server.
While using OAuth2 doesn’t require your user to leave your application.

To see a web server + minecraft server where you check a token, check out the examples.

Versions

Due to network protocol changes, currently the library only supports 1.21.2+ (768).
This has been tested to work in 1.21.2, 1.21.3, 1.21.4, 1.21.5, 1.21.6, 1.21.8, 1.21.9, 1.21.10 & 1.21.11.
Technically the networking protocol and authentication system should allow for any client with a version of 1.7+ to work.
But I’ve encountered plenty of small differences in networking between that and now that isn’t really documented anywhere.

Non-working versions

Versions that I’ve tested to not work and their vague reasoning on why.

• 1.21.1, 1.21 Failed to decode clientbound/minecraft:game_profile
• 1.20, 1.19.2, 1.19, 1.16.1, 1.12.2, 1.8 Found 1 bytes extra whilst reading packet 1
• 1.15 <No Error>
• 1.7.2 Key was smaller than nothing! Weird key!

Note that these are from the latest version of this library as of writing this.
In the past I have gotten different errors than what is written here.
Like 1.16.1 have complained about extra bytes in a different sequence.
And 1.12.2 and 1.8 have responded with IndexOutOfBounds errors in the past.

Server List Pings

The server implements legacy pings for all previous versions, including:

• Beta 1.8 to 1.3
• 1.4 to 1.5
• 1.6

And of course the modern server ping sequence.

Configuration

Everything that the client visually sees can be customized and how the token generates can also be overriden.

Server Configuration

A Token and Message generator can be supplied when starting a minecraft server.
The Token generator takes in the players username and uuid and must return a string that the client receives.
This token is then synced with the player to verify it later on.
The Message generator takes in the token and must return a valid text component that is displayed to the user upon a successful disconnection.

For more look at the ServerConfig.

Status Configuration

The favicon for server list ping can changed to any 64x64 png image.
The description displayed in the server list can be any valid Nbt text component.
You can also supply a legacy_decription which is just a simple string that is used in legacy ping packets,
and also if a client is too old to join.

Re-exports

pub use image;

pub use serde_json;

pub use simdnbt;

pub use uuid;

Structs

Message

The default message template displayed upon disconnect

Player

A player who joins, holds their Uuid and username

Server

The consumer end of the Minecraft server

ServerConfig

Config for the Minecraft Server

StatusConfig

Config for status packets

Token

Default token generator, a string of 10 random A-Z character

Enums

MCHAError

Top-level Error structure

ServerError

Errors that happen in the Minecraft server on each connection

TypeError

Errors related to writing and reading packets and their data types

Traits

MessageGenerator

Creates a text component message with a token as input

TokenGenerator

Generates a token based off a user, and optionally a different way to display it