Users, authentication, and RBAC
Combine local accounts, service accounts, OIDC providers, custom roles, ownership, and per-server collaboration without creating a lockout path.
Gameplane’s authentication and authorization system combines local user accounts, optional OIDC single sign-on, built-in and custom roles, per-server ownership, and per-namespace role bindings. The model prevents lockout by requiring at least one tested administrative recovery path before enabling OIDC-only mode.
Keep a local admin session open while testing the identity provider, and verify redirect URIs, claims, groups, and mapped permissions in a private session before enforcing SSO-only behavior.
Users and service accounts
Invite and edit local users, reset credentials deliberately, and give automation its own account rather than a shared login.
Local users are invited via the dashboard (Admin Settings → Users → Add user). Set the user’s initial password directly (or leave it blank for an OIDC-only account) and share it with them out of band; there is no built-in email invite flow. Gameplane has no API tokens yet. For automation, create a dedicated local user with an appropriate custom or built-in role (usually viewer or operator scoped to specific namespaces) and have scripts sign in as it, sending the session cookie and CSRF header as shown in the REST API reference.
Roles and permissions
Built-in and custom roles group explicit permissions for servers, backups, templates, users, and platform operations.
Built-in roles
Gameplane defines three built-in roles that cannot be deleted:
- Admin: Full access to all resources, including users, roles, and global settings.
- Operator: Manage game servers, backups, templates, and backup schedules. Read access to modules, backup destinations, cluster info, and the permission catalog.
- Viewer: Read-only access across the control panel (servers, backups, templates, modules, cluster info, permissions).
Custom roles
Create custom roles under Admin Settings → Roles to combine specific permissions. Each permission is either cluster-wide (Namespaced: false) or server-namespace-scoped (Namespaced: true). Cluster-wide permissions grant access to all namespaces; namespace-scoped permissions can be granted per-server via role bindings.
The permission catalog includes:
- Game servers: View servers, create/edit/control servers, use the console (RCON / PTY).
- Backups: View, create/delete, and restore backups; view and manage schedules.
- Game templates: View, create/edit, delete.
- Modules: View the catalog, install/upgrade/uninstall modules and sources.
- Backup destinations: View and manage destinations.
- Cluster: View nodes/version/storage, add nodes and mint kubeconfig.
- Users: View users and their role bindings, create/edit/delete users.
- Roles: View roles and the permission catalog, create/edit/delete custom roles.
- Audit log: View audit events.
- Global settings: View and manage global platform settings (authentication, notifications, telemetry, module upload limits).
- Network captures: Enable, start, stop, download, and delete packet captures (cluster-wide only).
Owner-only server operations (transferring ownership, editing collaborators, wiping data, deleting the server) require either the server’s owner or an admin. Operator-role users keep their other server permissions but cannot perform these four operations on servers they don’t own.
OIDC and SSO
Configure identity providers through Helm install-time settings or the dashboard, validate claims and role mappings, and test the flow in a private session before enforcing SSO-only mode.
Runtime configuration (dashboard)
Add OIDC providers under Admin Settings → Authentication → Add provider. Fill in the issuer URL, client ID, and client secret (stored securely in a Kubernetes Secret). The callback URL is automatically derived from your external URL setting.
Supported providers include Keycloak, Authentik, Google, GitHub, and any RFC-7519 compliant OpenID Connect provider. Detailed setup guides for Keycloak, Authentik, Google, and GitHub follow the same issuer/client ID/secret pattern.
When a user logs in via OIDC for the first time, Gameplane creates a user row with the viewer role. Admins must promote new OIDC users manually via the dashboard or custom role bindings.
Install-time role mappings
Install-time role mappings are not available in v0.2.0-beta.8.
Helm role mappings eliminate the need for a bootstrap-admin account in OIDC-only deployments. Operators configure group mappings at install time, and the first user to log in receives the correct role immediately based on their IdP group membership.
When deploying with Helm, set api.oidc.enabled=true, api.oidc.groupsClaim to the name of your IdP’s groups claim (e.g., "groups"), and configure api.oidc.roleMappings.{admin,operator,viewer} with a list of group names for each role. On first login, Gameplane matches the user’s group membership against the mappings and assigns the highest-privilege matching role.
After deployment, admins can override role mappings through the dashboard without restarting the API. Helm upgrades preserve dashboard customizations — they do not overwrite group mappings that have already been edited in the UI. For detailed Helm value examples and troubleshooting, see the OIDC provider setup documentation on GitHub.
LOCKOUT PREVENTION
Next guide: Audit, observability, and administration