keycloak-minecraft-idp when you want players to sign in to Keycloak with Minecraft-backed Microsoft accounts.
The plugin adds a Minecraft to Keycloak. It uses Microsoft OAuth, exchanges tokens with Xbox Live and Minecraft services, and resolves the to the Minecraft Java username when available or to the Xbox Gamertag for supported Bedrock logins.
It is a general-purpose Keycloak extension and is not tied to Grounds. You can use it in any Keycloak deployment that needs Minecraft-backed sign-in.
If you are setting up the provider, start with the installation guide and then continue with the configuration guide.
Quick Links
GitHub Repository
View the source code, releases, and implementation details.
Installation
Install the provider JAR into Keycloak and configure the required Microsoft app registration.
Configuration
Set up partner token handling, optional vault-backed secrets, and user attribute updates.
Features
- Supports Minecraft Java Edition sign-in through Keycloak
- Supports Bedrock logins by falling back to the Xbox Gamertag when applicable
- Uses the Xbox partner for stable brokered account linking
- Stores on the Keycloak user
- Optionally synchronizes Microsoft real-name claims into Keycloak profile fields
Login Resolution
Use these rules to understand which login identity Keycloak will store for the user. An determines whether the account can continue through Java or Bedrock login resolution.| Account state | Login identity |
|---|---|
| Java entitlement and Java profile exist | Minecraft Java username and UUID |
| Bedrock entitlement only | Xbox Gamertag |
| Java entitlement exists, no Java profile yet, Bedrock entitlement exists | Xbox Gamertag |
| Java entitlement exists, no Java profile yet, no Bedrock entitlement | Login fails until the Java profile is created in the Minecraft Launcher |
| No Java or Bedrock entitlement | Login fails |
Authentication Flow
The sign-in flow uses Xbox tokens to resolve Minecraft access and partner-scoped account identity.After installation, the provider appears in the Keycloak admin UI as
Minecraft.