Identity and security¶
Magic Stick uses a local-first identity architecture. Keycloak is the local OpenID Connect (OIDC) provider and identity broker. Envoy Gateway enforces the login before a protected HTTP route reaches an application. The appliance can therefore authenticate users while fully disconnected from cloud services.
Envoy Gateway is the only installed application gateway. The dashboard, all
operator-managed AppInstances, LiteLLM, AnythingLLM, and the KubeOpenCode
server use authenticated Gateway API resources. The bundled installation
contains no application Ingress resources.
Target Architecture¶
Browser
-> Envoy Gateway
-> OIDC login at local Keycloak
-> local user database (offline)
-> optional upstream Entra ID, Google, AWS, or another OIDC/SAML IdP
-> authenticated request to dashboard or application
kubectl
-> OIDC exec credential plugin
-> the same local Keycloak login and optional upstream broker
-> short-lived ID token with direct Magic Stick Kubernetes groups
-> Kubernetes API server OIDC authentication and RBAC
magicstick CLI or TUI
-> public Keycloak device-flow client
-> browser verification or a URL plus one-time code
-> short-lived access token with the same Magic Stick realm roles
-> Envoy JWT policy on api.<mDNS-domain>
-> dashboard control-plane API authorization
attached appliance monitor (TUI)
-> confidential magicstick-console client, secret mounted in-cluster only
-> short-lived token of the local console service account, no user or browser
-> cluster-internal dashboard API, which reads the console's current roles
from Keycloak on every authorization
Applications trust one stable local issuer. External enterprise identity providers are configured as upstream identity providers in Keycloak rather than integrated separately into every application. Replacing an upstream provider therefore does not change application routes or their OIDC clients.
Supported operating modes are:
| Mode | Login path | Internet required |
|---|---|---|
| Local standalone | Keycloak local account | No |
| Brokered enterprise | Keycloak forwards to Entra ID, Google, AWS, or another supported IdP | Only for the selected upstream IdP |
| Direct external provider | A deployment overlay replaces the OIDC provider settings at the gateway | Yes; intended as an escape hatch |
The recommended production mode is local Keycloak with optional upstream brokering. Keep at least one protected local break-glass administrator account so an upstream outage does not lock administrators out of the appliance.
Authorization Model¶
The local realm defines four initial roles:
| Role | Intended access |
|---|---|
magicstick-user |
Authenticated application user; minimal dashboard My instances launchpad |
magicstick-viewer |
Read-only dashboard and status access |
magicstick-operator |
Runtime application and model operations |
magicstick-admin |
Identity, security, and appliance administration |
Authentication and authorization remain separate. Envoy proves the identity
and forwards the OIDC access token only to backends that consume it. The
dashboard API validates that token with Keycloak and checks the relevant role
before every operation. LiteLLM remains protected by the same edge login and
role policy, but does not receive the OIDC token in Authorization because that
header belongs to LiteLLM's own Bearer sk-... API authentication. Upstream
groups should be mapped to the local Magic Stick roles in Keycloak.
Dashboard access is hierarchical: viewer permits read-only endpoints, operator
also permits module, instance, model, and credential operations, and admin also
permits appliance-wide settings and human-user administration. magicstick-user
alone receives only the dashboard My instances launchpad and its minimal
session/instance API; it does not grant control-plane or status access.
AppInstance access uses the same hierarchy at the Envoy edge. OIDC stores the
Keycloak access token in a host-only __Host-MagicStickAccessToken cookie;
Envoy's JWT filter validates that token and authorizes the selected minimum
realm_access.roles value before forwarding to the application. A route can be
made unauthenticated only with explicit spec.access.authentication: none.
Browser token cookies are scoped to the exact application hostname, never the shared appliance domain. The login provider remains shared, so visiting another service can reuse its sign-in without copying that service's token cookies to siblings. A global sign-out invalidates the central session; the edge checks session validity before forwarding later requests, even when another host still has an old cookie. Legacy Magic Stick token cookies are removed narrowly; unrelated application cookies are not erased.
The Gateway denies access when an authentication policy is missing and retains the callback check when a route-specific gate disappears. Admission rejects unsafe overrides and deletion of these baselines. Fresh activation requires a real admission deny probe, not only a rendered manifest. See identity validation.
The core instance-sharing capability adds allow-lists of stable Keycloak user and group IDs. For restricted instances, the API and gateway guard also verify live user status, effective minimum role, group membership (including subgroups). No license file is required for instance sharing. Administrators retain management visibility, but require an explicit grant to use the app or retrieve its private credentials. These are HTTP access controls, not Kubernetes tenant/network isolation.
Human browser sessions use OIDC Authorization Code Flow. Human kubectl
sessions use a separate public PKCE client and an exec credential plugin. The
Magic Stick CLI and TUI use a third public client with Device Authorization
Flow and send its Bearer access token to the dedicated control-plane API route.
None of these clients reuse browser cookies, client secrets, or each other's
client ID. Unattended machine integrations still need their own policy and
credential lifecycle; a renewable human device session is not a service
account.
The monitor attached to the appliance is the one deliberate exception to a
personal login. It signs in automatically as the Local console service
account so the appliance stays operable at the machine itself without a network
or a second device. Physical access to that keyboard therefore equals the
configured dashboard access: Administrator by default, or Operator, Viewer or
Off as chosen by an administrator. The identity has dashboard roles only, is
hidden from user lists, cannot be used to sign in to the browser dashboard or
kubectl, and a console with a lowered level cannot raise it again. Its tokens
are accepted only on the cluster-internal API connection, never through a
network-facing route. Root on the host, Kubernetes cluster administrators and
Keycloak administrators can read the generated secret; they already hold
equivalent or broader access. See
automatic sign-in.
Browser session lifetime¶
Local Keycloak login offers its native Remember me checkbox. Normal SSO sessions retain a 1,800-second idle timeout and a 36,000-second maximum. Opted-in sessions use 604,800 seconds idle and 2,592,000 seconds maximum. Access tokens remain 300 seconds; Envoy renews them using the existing refresh flow. Browser restart and standby do not revoke the remembered session, but explicit logout and the absolute maximum still end it. Use a fresh login to opt in after an upgrade. See Keycloak session timeouts.
The realm import contains these defaults. Existing realms are reconciled once
by keycloak-session-policy.sh in both Keycloak startup paths. Migration version
magicstickRememberMePolicyVersion=1 is stored in the realm attributes. Only
the unchanged original policy (rememberMe=true, 300/1,800/36,000-second token
and normal limits, both remember-me limits zero) is upgraded. Custom/disabled
policies are retained and marked as reviewed, with a sanitized message. A repeat
does not reapply defaults or overwrite later administrator changes.
Reads use the existing scoped setup client; writes authenticate separately with
the already provisioned bootstrap administrator. No Dashboard service account
receives manage-realm. Authentication, read, version, concurrent-change, write
and verification failures stop this migration with a fixed diagnostic code; they
never enable an unauthenticated fallback. Other realm attributes, ordinary
session policy, API keys and API token validation are unchanged. See the
isolated session checks.
Hostname changes and callback readiness¶
The first-run wizard and Settings save the configured local and public hosts. Flux updates the identity routes and runs the existing Keycloak startup reconciliation. Importing a changed realm file alone does not replace clients already stored in Keycloak's database.
The startup hook now completes in the foreground, without opening process 1's file descriptors. The existing scoped setup client updates only the configured human gateway redirect URIs, web origins and logout callbacks. Readback verifies the same client identity and exact redirect/origin sets before startup succeeds; failed writes, stale data or failed companion-client synchronization fail the hook instead of leaving a Ready server with old callbacks. Existing users, credentials, roles and unrelated client attributes are preserved. Callback paths for instances remain scoped to the explicit configured hosts; no wildcard host, additional realm permission or AppArmor ptrace grant is introduced. The existing administrative clients reconcile only role differences: an exact direct mapping is verified without posting the same grant again. Missing or unexpected mappings still require the existing authority and exact final readback; denied changes do not become success. Retry decisions are bounded by both the attempt limit and a ten-minute elapsed-time budget. Fixed step codes identify a failed companion-client reconciliation without exposing raw errors.
After an approved name change, wait for identity reconciliation to finish and open the new dashboard URL again. A saved authorization URL can contain stale login state; it is not a new login attempt. See the callback validation procedure.
Implemented Scope¶
The current implementation provides:
- Envoy Gateway
v1.8.5with Envoy Proxyv1.38.7as the primaryLoadBalancerdata plane - Keycloak with PostgreSQL in namespace
identity-system - runtime-generated database, bootstrap-admin, and OIDC client secrets
- a first-run wizard that creates the first human and recovery administrators without storing their passwords in Kubernetes
- a scoped Keycloak setup service account for first-run and callback reconciliation
- a separate
magicstick-user-adminservice account for dashboard user administration; it has user-query and user-management roles but no client, realm, impersonation, or identity-provider administration role - a separate
magicstick-federation-adminservice account for licensed dashboard federation; it has only identity-provider view/manage plusview-realm, and no user, client, realm-management, or impersonation role - an appliance-local identity CA and a CA-signed certificate for local
.localhostnames; the public CA can be embedded in OIDC kubeconfigs - an unprotected Keycloak route and a protected
auth-pilottest route - protected local and public dashboard
HTTPRouteresources - operator-generated local and public AppInstance
HTTPRouteresources with default SSO and optional user/viewer/operator/admin minimum roles - removal of edge-managed OIDC cookies before requests reach the Hermes API
gateway; authorization is completed at Envoy and the access token is
forwarded in the
Authorizationheader - per-instance callback routes on the shared dashboard hosts, so the same Keycloak client and browser session protect dynamically created instances
- a verified foreground Keycloak startup reconciliation for configured callback hosts and the instance callback paths needed by existing installations
- dashboard API token validation, a minimal user launchpad and viewer/operator/admin authorization
- a public
magicstick-clidevice-flow client and the JWT-protected, mDNS-publishedapi.<mDNS-domain>route used by the CLI and TUI - a confidential
magicstick-consoleservice-account client for automatic sign-in of the attached monitor, with an administrator-controlled access level - protected local and public routes for LiteLLM, AnythingLLM, and KubeOpenCode
with a minimum
magicstick-userrole - LiteLLM-specific OIDC token forwarding disabled after edge authorization, so
its UI and API retain their own virtual-key
Authorizationheader - removal of the bundled dashboard and AI application
Ingressresources - no human default password on new installations
- a public PKCE client
magicstick-kubernetes, agroupstoken mapper, and direct Viewer/Operator/Administrator groups for human Kubernetes access
The dashboard API accepts access tokens only when their azp is the browser
gateway client or magicstick-cli, their issuer matches the local realm, they
are unexpired, Keycloak still accepts them through userinfo, and the required
realm role is present. The edge JWT policy is an additional validation layer,
not a replacement for API authorization.
Gateway patch updates¶
Both the identity gateway and temporary first-run gateway explicitly select the
patched Envoy Proxy image. The Helm default alone is insufficient: an attached
EnvoyProxy without a merge type replaces the controller default.
The selected same-series patches follow the upstream
Envoy Gateway v1.8.5 upgrade guidance
and include fixes for authentication-filter crashes. This is not proof that a
historical, unsymbolized native crash had one particular upstream cause.
Upgrading from the older OIDC cookie format can require users to sign in once again; it does not remove local accounts. Validate authenticated dashboard and application access plus module/route disable, re-enable and cleanup without proxy restarts after a gateway update. Do not bypass TLS, authentication or the regression cleanup fence if that check fails.