YggdrasilAuthHelper

A standalone Java application for Yggdrasil authentication helper with GUI management interface.

Features

• Standalone Application: Runs as a regular Java application, no need for Java Agent setup
• System Properties Injection: Automatically sets system properties for authentication
• GUI Management Interface: Swing-based GUI for managing authentication servers and login sessions
• HOCON Configuration: Uses HOCON format for flexible configuration management
• Multiple Server Support: Add and manage multiple Yggdrasil authentication servers
• Session Management: Login and store multiple player profiles
• Automatic Server Discovery: Fetch server information automatically from API endpoints
• Profile Selection: Support for accounts with multiple game profiles
• Easy Deployment: Single JAR file with all dependencies included

Building

./gradlew build

The agent JAR will be generated in build/libs/YggdrasilAuthHelper-1.0-SNAPSHOT.jar

Usage

Standalone Mode

Run the application directly for configuration management:

# Use default config file (config.conf)
java -jar YggdrasilAuthHelper-1.0-SNAPSHOT.jar

# Use custom config file
java -jar YggdrasilAuthHelper-1.0-SNAPSHOT.jar my-config.conf

Launcher Integration Mode

Use with Minecraft launcher commands to automatically modify and execute them:

Standard Format (Default)

java -jar YggdrasilAuthHelper-1.0-SNAPSHOT.jar config.conf \
  java -jar minecraft.jar \
  --username OriginalUser \
  --version 1.21.6 \
  --gameDir /minecraft \
  --assetsDir /assets \
  --assetIndex 26 \
  --uuid original-uuid \
  --accessToken original-token \
  --userType msa \
  --versionType release

MultiMC Format

For MultiMC launcher compatibility, use the --format=multimc parameter:

java -jar YggdrasilAuthHelper-1.0-SNAPSHOT.jar config.conf --format=multimc \
  java -jar minecraft.jar \
  param --username \
  param OriginalUser \
  param --version \
  param 1.21.6 \
  param --gameDir \
  param /minecraft \
  param --uuid \
  param original-uuid \
  param --accessToken \
  param original-token \
  userName OriginalUser \
  sessionId token:original-token

Command Modification Examples

Standard Format:

Original command:

java -jar minecraft.jar --username OriginalUser --version 1.21.6 --gameDir /minecraft

Modified command:

java -javaagent:/path/to/authlib-injector.jar=https://authserver.com \
  -Xmx4G -XX:+UseG1GC \
  -Dcustom.property=value \
  -jar minecraft.jar \
  --username SelectedPlayerName \
  --version 1.21.6 \
  --gameDir /minecraft \
  --uuid selected-player-uuid \
  --accessToken selected-access-token \
  --userType msa \
  userName SelectedPlayerName \
  sessionId token:selected-access-token

MultiMC Format:

Original command:

java -jar minecraft.jar param --username param OriginalUser param --version param 1.21.6

Modified command:

java -javaagent:/path/to/authlib-injector.jar=https://authserver.com \
  -Xmx4G -XX:+UseG1GC \
  -Dcustom.property=value \
  -jar minecraft.jar \
  param --username param SelectedPlayerName \
  param --version param 1.21.6 \
  param --uuid param selected-player-uuid \
  param --accessToken param selected-access-token \
  param --userType param msa \
  userName SelectedPlayerName \
  sessionId token:selected-access-token

The application will:

1. Open a GUI for configuration management
2. When you click "确认并启动Minecraft", it will:
   • Replace existing authentication parameters with your selected profile values:
     • --username → selected player name
     • --uuid → selected player UUID
     • --accessToken → selected access token
     • --userType → "msa"
     • userName → selected player name (legacy)
     • sessionId → "token:access_token" (legacy)
   • Add missing authentication parameters to the end of command if not present
   • Add -javaagent:<authlib-injector-path>=<server-url> if authlib-injector is configured
   • Add custom JVM arguments and system properties
   • Execute the modified command to start Minecraft
   • Hide the GUI window during Minecraft execution
   • Automatically exit when Minecraft process terminates

Java Agent Support

YggdrasilAuthHelper includes a Java Agent that can modify Minecraft's bytecode at runtime to replace authentication parameters. This provides an alternative method for authentication that works by modifying the net.minecraft.client.Main class's main method arguments.

Features:

• Bytecode Modification: Uses ASM library to modify Minecraft client bytecode at runtime
• Automatic Parameter Replacement: Replaces --username, --uuid, --accessToken, and --userType parameters
• Parameter Completion: Adds missing authentication parameters if not present in original command
• authlib-injector Integration: Automatically loads and initializes authlib-injector with correct server URL
• Unified JAR: Agent mode and wrapper mode combined in a single JAR file
• No GUI Required: Agent runs without opening the graphical interface

Usage: The agent is automatically used when launching Minecraft through YggdrasilAuthHelper. It can also be used manually:

java -javaagent:YggdrasilAuthHelper-1.0-SNAPSHOT.jar=config.conf -cp minecraft.jar net.minecraft.client.Main [args...]

For detailed information about the Java Agent, see JAVA_AGENT_README.md.

Configuration File

The configuration file uses HOCON format. If the specified config file doesn't exist, it will be created automatically from the default template in resources. See example-config.conf for the structure:

servers = {
  # Server configurations will be added here automatically via GUI
}

sessions = [
  # Login sessions will be stored here automatically
]

options = {
  # Path to authlib-injector.jar if needed
  authlibInjector = null

  # Additional Java agents to load
  additionalAgents = [
    # "/path/to/agent1.jar"
    # "/path/to/agent2.jar"
  ]

  # Custom system properties to set
  systemProperties = {
    # "custom.property" = "value"
    # "another.property" = "another_value"
  }

  # Additional JVM arguments
  jvmArguments = [
    # "-Xmx2G"
    # "-XX:+UseG1GC"
  ]

  # Last selected profile (automatically managed)
  lastSelectedProfile = {
    serverId = "server-uuid"
    profileId = "player-uuid"
  }
}

GUI Features

Application Workflow

1. When the application starts, the GUI opens immediately
2. Review your authentication servers and login sessions
3. Add servers or login as needed
4. Select a profile using the "选择档案" (Select Profile) button
5. Click "确认并启动Minecraft" (Confirm and Start Minecraft) to apply settings
6. System properties are set for authentication using the selected profile
7. If Minecraft command is provided: GUI window hides and Minecraft starts with modified parameters
8. Application automatically exits when Minecraft process terminates

Adding Authentication Servers

1. Click "添加认证服务器" (Add Authentication Server)
2. Enter the server's API root URL (e.g., https://authserver.example.com)
3. The application will fetch server information automatically
4. Review and confirm the server details

Logging In

1. Click "登录" (Login)
2. Select an authentication server
3. Enter your username and password
4. If you have multiple profiles, select the one you want to use
5. Confirm to save the login session

Profile Selection

• Use "选择档案" (Select Profile) button to choose which profile to use for Minecraft
• Selected profile is highlighted with a star (★) and green border
• The lastSelectedProfile configuration is automatically saved

Managing Sessions

• View all saved login sessions in the "登录档案" (Login Profiles) tab
• Each session shows player name, UUID, username, and server information
• Selected profile is visually highlighted

Advanced Management

• Use "管理" (Manage) button for advanced server and session management
• Delete servers and sessions
• Refresh individual servers and session tokens
• Bulk management operations

Advanced Configuration

The agent supports advanced configuration options in the options section:

authlib-injector Integration

options = {
  authlibInjector = "/path/to/authlib-injector.jar"
}

Additional Java Agents

options = {
  additionalAgents = [
    "/path/to/agent1.jar"
    "/path/to/agent2.jar"
  ]
}

Custom System Properties

options = {
  systemProperties = {
    "custom.property" = "value"
    "minecraft.debug" = "true"
  }
}

JVM Arguments

options = {
  jvmArguments = [
    "-Xmx4G"
    "-XX:+UseG1GC"
    "-XX:+UnlockExperimentalVMOptions"
  ]
}

Development

The application is implemented in Kotlin and provides the following features:

• Standalone Application: Simple main method execution without Java Agent complexity
• System Properties Injection: Automatic setting of authentication-related system properties
• HOCON Configuration: Flexible configuration file management with automatic defaults
• HTTP API Client: Full Yggdrasil authentication protocol implementation
• Swing GUI: User-friendly interface for server and session management
• Server Discovery: Automatic fetching and validation of authentication server information
• Session Persistence: Secure storage and management of authentication tokens
• Easy Deployment: Single executable JAR with all dependencies

Agent API

The agent provides static methods to access configuration:

// Check if agent is initialized
YggdrasilAuthAgent.isInitialized()

// Get configuration manager
YggdrasilAuthAgent.getConfigManager()

// Get current configuration
YggdrasilAuthAgent.getConfig()

Technical Implementation

Application Architecture

The application uses a simple main method approach with Swing GUI:

fun main(args: Array<String>) {
    // Load configuration
    loadConfig()

    // Initialize launcher
    initializeLauncher()

    // Show GUI (non-blocking)
    showGUI()
}

This approach ensures:

• Simple deployment as a standalone JAR
• GUI runs in Swing's Event Dispatch Thread
• No complex thread synchronization needed
• Easy to use and debug

System Properties Injection

The agent automatically sets authentication-related system properties:

• minecraft.player.name - Player display name
• minecraft.player.uuid - Player UUID
• minecraft.access.token - Authentication token
• minecraft.api.auth.host - Authentication server URL
• Custom properties from configuration

Dynamic Agent Loading

Uses Java Instrumentation API to load additional agents at runtime:

• Parses JAR manifest for agent class
• Adds agent JAR to classpath
• Invokes agent initialization methods

Dependencies

• Kotlin JVM
• TypeSafe Config (HOCON)
• OkHttp (HTTP client)
• Gson (JSON parsing)
• Apache Commons Codec (Base64 utilities)
• Java Swing (GUI)
• Java Instrumentation API