Skip to main content
Authentication is off by default. With it off, the API is open and every request runs in one built-in default tenant. Turn it on by choosing a provider with AUTH_PROVIDER, or auth.enabled and auth.type in the chart. Every Functions and Metrics RPC and POST /functions/<id>/invoke require credentials once a provider is set. /healthz, /scaling and the UI’s static files do not.

How callers map to tenants

The provider resolves each request to a caller and the caller’s tenant: a Keycloak organization, a Zitadel organization or the gateway’s tenant header. The first time the server sees a tenant, it creates a tenant row for it, and the same for each user within it. Functions, versions, invocations and secrets all belong to a tenant, and a caller sees only their own tenant’s. A caller is a person or a service account. A service account acts on its own behalf and gets no user row. The providers also carry roles, admin, creator and viewer, which govern AuthService itself: members and service accounts. Alchemy does not check them on its own RPCs yet. Any authenticated caller in a tenant can use every Functions and Metrics RPC. Alchemy is meant to run one tenant per deployment. See Overview.

Keycloak

Alchemy is Keycloak’s only client. People sign in through Alchemy’s own Login RPC with a password, which the server checks against the realm with the direct access grant, and the browser gets an HttpOnly session cookie, alchemy_sid. Nothing redirects to Keycloak, so Keycloak features beyond a password, such as MFA or federated login, are not reachable. Keycloak 26 or newer.
issuer is the realm URL and must match what the realm advertises. clientId and clientSecret name Alchemy’s confidential client. Its service account administers the realm on Alchemy’s behalf. With keycloak.adminUser and keycloak.adminPassword, the master-realm admin, the server creates the realm and client on boot when they are missing. Without them, the realm’s owners create both, with the client’s service account holding realm management rights. Either way the server converges organizations, its client roles and the token shape on every boot. A bearer token must carry exactly one organization. Request the organization scope, or organization:<alias> for a user in more than one.

Zitadel

Alchemy is Zitadel’s only client too. People sign in through Alchemy’s Login RPC and the browser holds a session cookie.
issuer is the Zitadel base URL and must equal the issuer Zitadel advertises. pat is a machine user’s personal access token with instance rights. The server provisions its project in Zitadel on boot. A bearer token must carry the user’s organization, which Zitadel adds when the client requests the resourceowner scope.

Proxy

With proxy, a gateway in front of Alchemy signs people in and tells Alchemy who they are. Alchemy verifies nothing itself. It reads three headers:
The gateway must strip any copy of these headers a client sends, and the network must make the gateway the only way to reach the server. Anyone who can reach the server directly can claim any identity.
Set auth.proxy.tenant (AUTH_PROXY_TENANT) to pin the one tenant this deployment serves. A request for any other tenant is refused with permission_denied. Left empty, Alchemy accepts any tenant the gateway names. In proxy mode, AuthService has no sign-in of its own. GetAuthConfig answers with an empty issuer and the other AuthService RPCs are unimplemented.

Bootstrap a tenant

A fresh deployment has no one in it. The bootstrap values create a tenant on every boot and let someone in: A bootstrap admin closes sign-up. Register is refused and everyone else joins by invitation.

Credentials and secrets

Passwords, client secrets and the PAT go in the runtime Secret, never the ConfigMap. Without existingSecret, the chart puts AUTH_CLIENT_SECRET, AUTH_ADMIN_PASSWORD, AUTH_BOOTSTRAP_CLIENT_SECRET, AUTH_PAT and AUTH_BOOTSTRAP_ADMIN_PASSWORD there from their values. With existingSecret, add the ones your provider uses to that Secret yourself. auth.uiOrigin (AUTH_UI_ORIGIN) is the origin the UI is served from, normally the ingress host. An https origin marks the session cookie Secure.

Tokens for code

Code calls Alchemy with a bearer token. A service account exchanges its client id and secret for one through the server, so clients need no route to the provider:
Send it on every call, and mint a new one as it nears expiresIn seconds:
Tenant admins create service accounts with CreateServiceAccount and rotate them with RotateServiceAccountSecret. A secret is returned only by those two calls and cannot be read later.

The web UI

The web UI that ships in the server has no sign-in page yet. With authentication on, its requests carry only a session cookie that some other page set, so it works behind a proxy gateway and not yet on its own with Keycloak or Zitadel.