KmAuth - Minecraft Authentication Server

A custom Minecraft authentication server built with Spring Boot that implements the Yggdrasil protocol and supports Microsoft account linking.

Features

• Yggdrasil Protocol Support: Full compatibility with standard Minecraft authentication
• Microsoft Account Integration: Link Microsoft/Xbox accounts to import official profiles
• Authlib-Injector Compatible: Works with authlib-injector for easy client setup
• Multi-Profile Support: Users can have multiple player profiles
• Skin & Cape Support: Custom skins and capes per player
• Invite System: Optional invite-only registration
• Web UI: Built-in registration and account management pages

Quick Start

Prerequisites

• Java 21 or later
• Maven 3.8+
• (Optional) PostgreSQL or MySQL for production

Building

cd KmAuth
mvn clean package

Running

# Using Maven
mvn spring-boot:run

# Or using the JAR
java -jar target/kmauth-1.0.0-SNAPSHOT.jar

The server will start on http://localhost:8080 by default.

First Steps

1. Open http://localhost:8080/register in your browser
2. Create an account
3. Configure your Minecraft launcher (see below)

Configuration

Edit src/main/resources/application.yml or set environment variables:

Basic Settings

kmauth:
  server-name: My Server           # Display name
  base-url: http://localhost:8080  # Public URL of your server
  require-invite: false            # Require invite codes for registration
  allow-microsoft-auth: true       # Enable Microsoft account linking
  allow-password-auth: true        # Enable username/password auth

Database Configuration

H2 (Default - Development)

spring:
  datasource:
    url: jdbc:h2:file:./data/kmauth
    driver-class-name: org.h2.Driver
    username: sa
    password:

PostgreSQL (Recommended for Production)

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/kmauth
    driver-class-name: org.postgresql.Driver
    username: kmauth
    password: your_secure_password
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect

MySQL

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/kmauth?useSSL=false&serverTimezone=UTC
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: kmauth
    password: your_secure_password
  jpa:
    properties:
      hibernate:
        dialect: org.hibernate.dialect.MySQLDialect

Microsoft OAuth Setup

To enable Microsoft authentication:

1. Go to Azure Portal
2. Navigate to "App registrations" → "New registration"
3. Configure:
   • Name: KmAuth (or your server name)
   • Supported account types: "Personal Microsoft accounts only"
   • Redirect URI: http://your-server:8080/oauth/microsoft/callback
4. Copy the Application (client) ID
5. Create a client secret under "Certificates & secrets"

kmauth:
  microsoft:
    client-id: your-client-id
    client-secret: your-client-secret
    redirect-uri: http://your-server:8080/oauth/microsoft/callback

Or use environment variables:

export MICROSOFT_CLIENT_ID=your-client-id
export MICROSOFT_CLIENT_SECRET=your-client-secret
export MICROSOFT_REDIRECT_URI=http://your-server:8080/oauth/microsoft/callback

Client Setup

Using Authlib-Injector (Recommended)

1. Download authlib-injector
2. Add to your Minecraft launch arguments:

   -javaagent:authlib-injector.jar=http://your-server:8080
   

Using JVM Arguments (Without Authlib-Injector)

Add these JVM arguments to your Minecraft launcher:

-Dminecraft.api.auth.host=http://your-server:8080/authserver
-Dminecraft.api.session.host=http://your-server:8080/sessionserver
-Dminecraft.api.services.host=http://your-server:8080

Supported Launchers

• Prism Launcher / PolyMC: Add account → Microsoft → Use custom auth server
• MultiMC: Edit instance → Settings → Custom commands
• Fjord Launcher: Native authlib-injector support
• HMCL: Native third-party auth support

Server Setup (Minecraft Server)

For Minecraft servers to verify players against your auth server:

Using Authlib-Injector on Server

Add to your server start script:

java -javaagent:authlib-injector.jar=http://your-auth-server:8080 -jar server.jar

Paper/Spigot Servers

If not using authlib-injector, the server must be in offline mode and use a plugin for verification.

API Endpoints

Authentication (Yggdrasil)

Endpoint	Method	Description
/authserver/authenticate	POST	Login with username/password
/authserver/refresh	POST	Refresh access token
/authserver/validate	POST	Validate token
/authserver/invalidate	POST	Invalidate token
/authserver/signout	POST	Sign out (invalidate all tokens)

Session Server

Endpoint	Method	Description
/sessionserver/session/minecraft/join	POST	Client join request
/sessionserver/session/minecraft/hasJoined	GET	Server verification
/sessionserver/session/minecraft/profile/{uuid}	GET	Get player profile with textures

Profile Lookup

Endpoint	Method	Description
/users/profiles/minecraft/{name}	GET	Get profile by name
/profiles/minecraft	POST	Bulk profile lookup

Microsoft OAuth

Endpoint	Method	Description
/oauth/microsoft/login	GET	Start Microsoft OAuth flow
/oauth/microsoft/callback	GET	OAuth callback
/oauth/microsoft/authenticate	POST	API authentication with code

Compliance Note

This authentication server is designed for private servers and works alongside Microsoft authentication rather than replacing it. When Microsoft account linking is enabled:

• Users authenticate through Microsoft's official OAuth
• Player UUIDs and profiles come from official Minecraft accounts
• Skins and capes are imported from official profiles

This approach ensures compliance with Minecraft's Terms of Service while allowing self-hosted infrastructure.

Development

Project Structure

src/main/java/me/kmathers/kmauth/
├── config/          # Configuration classes
├── controller/      # REST controllers
├── dto/             # Data transfer objects
├── exception/       # Exception handling
├── model/           # JPA entities
├── repository/      # Data repositories
└── service/         # Business logic

Running Tests

mvn test

Building for Production

mvn clean package -Pprod

Troubleshooting

"Invalid token" errors

• Tokens expire after 30 days by default
• Check that your server time is synchronized
• Ensure the client is sending the correct clientToken

Microsoft auth not working

• Verify client ID and secret are correct
• Check redirect URI matches exactly
• Ensure your Azure app allows personal Microsoft accounts

Players can't join server

• Server must use authlib-injector pointing to same auth server
• Check firewall allows connections between server and auth server
• Verify session hasn't expired (30 second window)

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.