31 lines
1.9 KiB
Markdown
31 lines
1.9 KiB
Markdown
# Admin OIDC setup
|
|
|
|
The admin console uses Keycloak OIDC and JWT-backed NextAuth sessions.
|
|
|
|
## 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 rejects sign-in when the required role is absent, even when Keycloak authentication itself succeeds. Existing browser sign-in accepts realm or configured-client roles; this behavior is unchanged.
|
|
|
|
## Read-only machine API access
|
|
|
|
The [admin API guard](admin-api-authentication.md) independently verifies signed Keycloak access tokens. Machine tokens must include `KEYCLOAK_CLIENT_ID` in `aud` and `KEYCLOAK_REQUIRED_ROLE` in `resource_access[KEYCLOAK_CLIENT_ID].roles`. A realm role alone is **not** sufficient for bearer access. The identity provider must emit both the portal audience and this client role; a token's `azp` is not an audience substitute.
|
|
|
|
Verification uses the HTTPS issuer's `/protocol/openid-connect/certs` JWKS endpoint and RS256 only. It does not use `KEYCLOAK_CLIENT_SECRET`, exchange tokens, or create a browser session. Browser client configuration above remains required for interactive SSO. Provisioning or changing machine clients, role/audience mappers, credentials, and production deployment requires separate operational approval; this source implementation performs none of those operations.
|