minecraft-account-manager/docs/admin-oidc-keycloak-setup.md

Admin OIDC setup

The admin console will use Keycloak OIDC and JWT-backed Auth.js sessions, following the established pattern in the sibling Retro application.

Application environment

• AUTH_SECRET
• NEXTAUTH_URL
• KEYCLOAK_ISSUER_URL
• KEYCLOAK_CLIENT_ID
• KEYCLOAK_CLIENT_SECRET
• KEYCLOAK_REQUIRED_ROLE (defaults to minecraft-account-manager-admin)

Keycloak client

Create a confidential OpenID Connect client with standard authorization code flow enabled and direct access grants disabled.

Recommended client ID: minecraft-account-manager-admin

Allow exact callback and logout URLs for each environment. Avoid wildcard origins and redirect URLs.

Create the realm role minecraft-account-manager-admin and assign it directly or through an admin group. Ensure realm roles are emitted in realm_access.roles.

The admin console will reject sign-in when the required role is absent, even when Keycloak authentication itself succeeds.