> ## Documentation Index
> Fetch the complete documentation index at: https://grounds-docs-platform-architecture.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and prepare the Keycloak Minecraft identity provider

<Info>
  **Prerequisites**:

  * A running Keycloak instance
  * JDK 21 available locally if you want to build from source
  * A Microsoft Azure App Registration for the <Tooltip tip="A sign-in handled by an external identity provider and then mapped back to a Keycloak user.">brokered login</Tooltip> flow
</Info>

<Note>
  The provider uses Microsoft's consumer OAuth endpoints. Corporate or `common` tenant configurations are not suitable for this flow because Xbox Live authentication requires the consumer setup.
</Note>

Use these steps to install the provider in Keycloak and prepare it for configuration.

<Steps>
  <Step title="Create the Azure App Registration">
    Create a Microsoft app registration with these settings:

    * Redirect URI: `https://your-keycloak-url/realms/{realm}/broker/{alias}/endpoint`
    * Delegated API permission: `XboxLive.signin`
    * Client secret: create one under `Certificates & secrets`

    The redirect URI must use the Keycloak <Tooltip tip="A Keycloak login source that delegates authentication to another system.">identity provider</Tooltip> alias. The default alias is usually `minecraft`, so the redirect URI is typically `https://your-keycloak-url/realms/{realm}/broker/minecraft/endpoint`. If you change the alias in Keycloak, update the redirect URI to match.

    The Keycloak identity provider later uses the Azure app's client ID and client secret.
  </Step>

  <Step title="Check Minecraft API Whitelisting">
    Some Minecraft authentication scenarios require Mojang or Minecraft API whitelisting in addition to the Azure OAuth setup.

    * Reference: [Minecraft help article](https://help.minecraft.net/hc/en-us/articles/16254801392141)

    If the app registration is not allowed to access the relevant Minecraft services, login or <Tooltip tip="Ownership checks that confirm whether the account has access to Minecraft Java or Bedrock.">entitlement</Tooltip> checks can fail even when the Microsoft OAuth setup is correct.
  </Step>

  <Step title="Obtain the Provider JAR">
    Use the published artifact from GitHub Packages:

    * Maven repository: `https://maven.pkg.github.com/groundsgg/keycloak-minecraft-idp`
    * Artifact: `gg.grounds:keycloak-minecraft-idp:<version>`

    Or build it from source:

    ```bash theme={null}
    ./gradlew shadowJar
    ```

    The build output is a single shaded JAR named `keycloak-minecraft-idp.jar`.
  </Step>

  <Step title="Install the Provider into Keycloak">
    Copy the JAR into Keycloak's providers directory:

    ```bash theme={null}
    cp keycloak-minecraft-idp.jar /opt/keycloak/providers/
    ```

    Then rebuild Keycloak:

    ```bash theme={null}
    /opt/keycloak/bin/kc.sh build
    ```

    Restart Keycloak after the build completes.

    <Check>
      Verify that Keycloak starts without provider loading errors before you continue.
    </Check>
  </Step>

  <Step title="Add the Identity Provider">
    In the Keycloak admin UI:

    1. Open your realm.
    2. Go to `Identity Providers`.
    3. Click `Add provider`.
    4. Select `Minecraft`.

    Continue with the [configuration guide](/deploy/keycloak-minecraft-idp/configuration) to fill in the required provider fields.

    <Check>
      Verify that `Minecraft` appears in `Identity Providers` before you move on to configuration.
    </Check>
  </Step>
</Steps>