Getting a token locally — the dev IdP that comes up with `forge env up` for a real browser sign-in (start here), what it declares vs. what a deploy-time job converges and publishes, hand-minting against a shared secret for API-only smoke tests, and the traps that are not your wiring (host-header instance routing, opaque-vs-JWT access tokens).
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Dev Loop?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/reliant-labs-dev-loop)
---
name: dev-loop
description: Getting a token locally — the dev IdP that comes up with `forge env up` for a real browser sign-in (start here), what it declares vs. what a deploy-time job converges and publishes, hand-minting against a shared secret for API-only smoke tests, and the traps that are not your wiring (host-header instance routing, opaque-vs-JWT access tokens).
---
# Authenticating locally
Dev relaxes only NON-security ergonomics (permissive CORS, verbose errors). **Authentication is enforced in every mode**: `SetupAuth` builds a real validator whether dev or prod, and no environment variable turns it off. So a local call to a protected RPC needs a real token.
**If anything you are building runs in a browser, use the dev IdP (option 1).** The shared-secret path below looks cheaper and is the usual wrong turn: it gets you a token for `curl` and leaves you with no sign-in flow, so a frontend still shows a page of 401s and the next move is hand-rolling a credential-injecting shim that has to be deleted later. The sign-in screen and the login broker behind it are already written — they need configuration, not code.
## 1. A real browser sign-in against the dev IdP (start here)
There is nothing to set up:
```sh
forge env up dev
```
**Zitadel is declared infrastructure.** `deploy/kcl/dev/main.k` names this environment's servers — postgres and `idp` — so bringing the environment up brings the IdP up, the same way it brings up the database. Each is READY before anything that dials it starts: forge waits on Zitadel's own `/debug/ready`, which reports CONVERGED rather than merely listening (the first boot runs the whole declarative setup before it serves).
**Nothing here runs in a container.** Both servers are `forge.HostInfra` declarations, so a scaffolded project starts ZERO containers. Zitadel is a single static Go binary: forge downloads the pinned version once, verifies it against a checksum committed in forge itself, caches it under the user cache dir, and supervises it as a host process. Its state lives in its OWN database on that same postgres, so the two schemas cannot collide.
**The container is still there if you want it.** `docker-compose.yml` still defines `idp` (and the `idp-db` it needs); in `deploy/kcl/dev/main.k`, drop the `idp` `forge.HostInfra` entry and add a compose-bound workload to `_workloads` — `fw.Workload {name = "idp", runtime = forge.OnCompose {service = "idp", env = {"IDP_PORT": str(_idp_port)}}}`. The identity step needs the `engine = "zitadel"` infra entry (`IdentityOnHost.infra`), so on the container path run the identity against it by hand or bring your own issuer.
It is scaffolded only for a project that declares a **frontend** — a project authenticating with API keys, a worker, or a service with no browser never gets it.
**Most of the IdP is DECLARED, not provisioned.** `idp-steps.yaml`, next to the compose file, describes the instance, the organization, the human you sign in as, and a service account; Zitadel converges to it on first boot, writing that service account's personal access token beside the IdP's database (`~/.forge/idp/<host>_<port>_<database>/pat.txt`, so a second clone whose IdP shares that database finds it) and copying it to `.forge/idp/pat.txt`.
**Where the PAT lives, and going back.**
- Zitadel writes the token only when it initializes its database. forge keeps it beside that database, in `~/.forge/idp/<key>/pat.txt`, where `<key>` is `localhost_<idp_database_port>_<idp_database>` (`ls ~/.forge/idp/` shows it).
- forge keeps `.forge/idp/pat.txt` as a copy, owner-only. It reads that copy when the shared file is missing, and publishes it to the shared file once it has signed in with it.
- An older forge reads only `.forge/idp/pat.txt`, so pinning back to one keeps working.
- To restore a copy by hand: `install -m 600 ~/.forge/idp/<key>/pat.txt .forge/idp/pat.txt`, or the reverse with a token you know works against this database.
- None of this touches the IdP's database or its users.
The launch banner prints where to sign in and the credentials. The account is the one `idp-steps.yaml` declares — `admin@<project>.localhost`, password `Password1!` — and that file is where you change it. Editing it later does nothing on its own: the steps run ONCE, when the instance is created (the file says how to rebuild).
### The identity step converges what cannot be declared
An OIDC client's `client_id`, and the Zitadel project id that becomes the token audience, are GENERATED by the server when the project and the application are registered, so there is nowhere to write them down in advance. The dev env therefore declares **the users**, not a job:
```python
# deploy/kcl/dev/main.k (on the Bundle)
identity = forge.ManagedIdentity {
runtime = forge.IdentityOnHost {infra = "idp"}
# roles, machine_users, seed_users, ... (see `deploy/managed-identity`)
}
```
`forge env up` converges that declaration on the host IdP with the **same library the control plane runs for hosted envs** (`pkg/identity`), authenticating with the bootstrap PAT (`idp_pat_path`). It runs after the IdP is ready and before any host service starts, and it is idempotent: a second run writes nothing. It converges the project and roles, the application (its redirect and sign-in URIs derived from the frontend's origin), declared members, seed users, machine users and the login broker's account. The env lands in the server's **default instance**: the dev IdP answers only to localhost.
What it publishes:
- **`.forge/identity/<name>.json`** (non-secret): issuer, audience, scopes, the signing-key snapshot, client ids, redirect and login URIs.
- **the env's secret store** (`secrets/dev.yaml`): everything a host process reads, under the env var name the process reads it as: `JWT_ISSUER`, `JWT_AUDIENCE`, `OIDC_CLIENT_ID`, `OIDC_REDIRECT_URI`, `IDP_BASE`, `IDP_BROKER_TOKEN`, ... plus `<USER>_MACHINE_KEY` for each declared machine user. The API gets them through `forge.IdentityRef`, which the render fills for you; you copy nothing. The broker token is reused while it is valid and rotated before it expires, never printed.
`forge env up` does not demand those store keys beforehand (they cannot exist before the first converge). A seed user's password is the one thing you supply: `forge secret set --env dev DEV_PASSWORD`, named by the seed user's `password_secret`.
If the converge fails the stack still starts, without sign-in, and the message names the IdP log.
Nothing else is needed on the frontend. Sign-in is native: the browser POSTs to this app's own `/auth/login` and the SERVER runs the OIDC flow with the client id above, so the bundle has nothing to configure (see `auth/frontend`).
### Mail, owners and the v2 sign-in methods in dev
Invitations, address verification, password reset and magic links are EMAIL. In dev that mail goes to **Mailpit**, declared like the IdP:
```kcl
# deploy/kcl/dev/main.k, in infra
forge.HostInfra {name = "mail", engine = "mailpit", port = _mail_port}
```
Mailpit is a pinned, checksummed binary supervised as a host process, like Zitadel. `port` is its SMTP port (plain, loopback, no auth); its web UI is on **port + 7000** (1025 → `http://localhost:8025`), and `forge env up` prints it as `Mail: …`. Messages persist in `mailpit.db` under the entry's data directory (`.forge/hostinfra/<name>/` unless it sets `data_dir`). The identity step points the dev IdP's SMTP at it (`IdentityOnHost.mail` names the entry; with exactly one mailpit it is found on its own). A declaration's own `smtp` still wins. Compose users: `docker-compose.yml` has a digest-pinned `mailpit` service.
With mail available, the dev env gets the SAME policies a hosted env gets from the same `identity.k`:
- **`owners`** are created, granted `owner_role`, and — while they have no credential — sent ONE invitation, which lands in Mailpit and links to `<frontend>/auth/invite?userID=…&code=…`. Re-sent at most every 7 days, 3 times in all; never revoked when removed. Without mail they are created and granted, and `forge env up` says they cannot be invited.
- **`signup`, `methods`** converge the IdP's login policy exactly as on hosted (the OTP-email factor magic links redeem included), and the broker reads them from `IDP_LOGIN_POLICY` (the `LOGIN_POLICY` document, `"mail": "dev"`), written to the store like every other identity output.
- **Passkeys** in dev use relying party `localhost`, whatever `passkey_rp_id` the hosted envs use: a passkey is bound to the host the browser is on.
- **`social`** providers need a SEPARATE DEV OAuth app at Google/GitHub whose callback is the dev IdP's `http://localhost:<idp port>/idps/callback` (printed by `forge env up`); set its secret with `forge secret set --env dev <client_secret name>`. A provider whose secret is missing is left out with a warning; the other methods still work.
One known difference: dev mail uses Zitadel's own templates, hosted mail the platform relay's. The links and codes are identical.
**To use an IdP forge did not start**, declare no `identity` for the env and set `jwt_issuer`, `oidc_client_id` etc. in `config.k` yourself (bring your own issuer). A workload that sets a field the identity fills is refused at render, naming both.
### Ports
**The IdP's port is FIXED, not ephemeral**, because the issuer in every token it mints is derived from it. It is DECLARED ONCE, in `deploy/kcl/dev/main.k`:
```kcl
_idp_port = plugin.allocate_port(8080, option("worktree") or "")
_idp_origin = "http://localhost:${_idp_port}"
```
Everything that has to agree reads that one variable: the IdP binds it (`HostInfra.port`, or `OnCompose.env`'s `${IDP_PORT}`), and the identity step dials and registers it (it reads the port off the `idp` infra entry). `allocate_port` rather than `resolve_port` because a port that stepped off a busy neighbour between runs would invalidate the `iss` of every issued token and the registered redirect URI. **To move it, change the base in that file** — not `IDP_PORT` in your shell, and not the compose file; those move the server alone and leave every other reference on the old port.
**The frontend's port does NOT need pinning.** A frontend that signs in keeps the kernel-assigned dev port forge hands it, so two dev stacks can run and sign in at the same time. That works because what the identity step registers is a **glob**, not a URL: Zitadel matches redirect URIs as patterns whenever the app is in `devMode` (which the job always sets for the dev SPA), so `http://localhost:*/auth/callback` matches whatever port this run got. A single `*` spans the port and does not cross a `/`, so a different host or path is still refused. Under a `base_path` the job composes the glob from the origin pattern plus the base path (`http://localhost:*/<base_path>/auth/callback`).
**No browser is ever sent to that URI.** Sign-in is native — the SERVER runs the OIDC flow (`internal/app/login_broker.go`) and the browser only ever talks to this app. The redirect URI still has to be registered and still has to match, because the issuer validates it on the auth request the server makes; it is a value both sides must agree on rather than a place anything navigates to. Registering a glob therefore relaxes far less than it did under the old browser flow: there is no authorization code travelling through a user agent to be redirected anywhere.
**It is still dev-only.** Wildcard redirect URIs are not permitted by the OIDC standard, and upstream offers the glob only for a client in DevMode. It is defensible for the dev IdP on `localhost` holding accounts that exist only on this machine, and nowhere else — pin a literal URI for any deployed environment.
Pinning a dev port is still available if you want a stable URL — set `port: <n>` in forge.yaml and put the literal URI in `config.k`.
## 2. Mint one against a shared secret — API smoke tests only
No IdP, no container, **and no sign-in flow**. Appropriate for `curl`-ing an RPC or a scripted check; not appropriate for anything with a browser. The token carries whatever claims you typed, so it never exercises the claim shape your real issuer produces.
Set `jwt_signing_method: "HS256"` in `deploy/kcl/dev/config.k` and a `jwt_secret` in the env's secret store (`forge secret set --env dev JWT_SECRET`), then sign with the same secret:
```go
// go run ./tmp-token — delete it afterwards; never commit a signer.
tok := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
"sub": "dev-user", "email": "dev@example.com",
"iat": time.Now().Unix(), "exp": time.Now().Add(time.Hour).Unix(),
})
s, _ := tok.SignedString([]byte(os.Getenv("JWT_SECRET")))
fmt.Print(s)
```
`jwt_signing_method` must AGREE with the key material: an HS* secret means HS256/384/512, and leaving the default `RS256` while setting `jwt_secret` to a shared secret rejects every token you mint.
## 3. Your real staging IdP
Point `jwt_issuer` at it. Nothing local is needed beyond network reachability, and the claim shape is exactly production's.
## Traps that are not your wiring
**The dev IdP answers to ONE hostname, and it is `localhost`.** Zitadel decides which instance a request is for by matching the request's **Host header** against that instance's registered domains — so a fetch to `http://idp:8080` from inside a compose network is answered `Instance not found`, not served, however correct the URL is. There is no in-network alias to configure around it: `TrustedDomains` in the steps file does not add one (verified), and neither the admin nor the system API exposes one either.
On the scaffolded host-process path this simply does not come up: everything — the browser, the app, the identity step — reaches the IdP at the same `http://localhost:<idp port>`, so `jwt_issuer` and `jwt_jwks_url` name one origin, they agree with the `iss` in every token, and discovery would work too. The identity step uses that origin as both the address it DIALS and the origin it REGISTERS, because on the host those are the same address.
It comes up the moment something runs in a container. **A project using the dev IdP runs its app with `forge env up`, not `docker compose up app`** — a containerized app would reach the IdP only by an in-network name the instance does not know. If you genuinely need that, the escape hatch is a header, not a URL: Zitadel honours `x-zitadel-instance-host: localhost` (verified) for instance selection. Nothing in forge's config sends it — `jwt_jwks_url` is a URL, not a request template — so that path means a custom HTTP client in `SetupAuth`. The job's `--host` / `--browser-origin` flags exist to bridge the same split for a job running inside a compose network.
*(An IdP having two hostnames is the general problem, and `jwt_jwks_url` taking precedence over discovery is forge's general answer to it — OIDC Discovery §4.3 requires a document's `issuer` to equal the URL it was fetched from, so a two-hostname deployment cannot be described by discovery alone.)*
**Some IdPs issue OPAQUE access tokens.** An opaque token is a random string, not a JWT, and will never validate against a JWKS however correct everything else is — the server rejects it with `token contains an invalid number of segments` while sign-in itself looks completely successful.
Zitadel decides this **per application**, not per request: an OIDC app is created with `accessTokenType: OIDC_TOKEN_TYPE_BEARER` (opaque) unless you say `OIDC_TOKEN_TYPE_JWT`. `forge env up` registers it as JWT, and re-running converges an app that was registered wrong. Because the choice is on the app, no `resource` parameter on the request can rescue an app left on the default — which is the opposite of the providers where asking for a registered API resource is the fix.
`jwt_audience` must equal what the token actually carries. Zitadel puts the **client id** in `aud` (alongside the project id) — the same `audience` key the job publishes.
**The scaffolded IdP serves the built-in (v1) sign-in pages.** Zitadel v4 defaults `LoginV2.Required` to true, which routes `/oauth/v2/authorize` at a login UI shipped as a SEPARATE artifact; with it absent the sign-in page 404s and the redirect flow dead-ends after an authorization request that looked fine. forge sets it false so one server is the whole IdP. It also turns off the passkey/2FA enrollment NUDGE (`PasswordlessType: 0` **and** `MfaInitSkipLifetime: 0s`) — both are needed, and neither alone is enough to skip the interstitial.
## Reading the failures
| symptom | cause |
| --- | --- |
| Server refuses to start, naming a URL | The issuer or JWKS endpoint is unreachable or wrong. Intended: it fails loudly instead of 401ing every request. (A fresh `jwt_jwks_snapshot*` is the one thing that lets it start while the issuer is down; `auth/shared-issuer` has the rules.) |
| `Instance not found` from the IdP | Reaching it by a hostname it does not know — almost always the compose service name from inside the network. Use `localhost:<IDP_PORT>` (above). |
| Every call 401s, token looks like a random string | Opaque access token — the app is registered with the default token type. Re-run `forge env up` to re-converge it. |
| Every call 401s, `alg` complaint | `jwt_signing_method` disagrees with the key material (HS\* secret vs RS\*/ES\* JWKS). |
| `iss` mismatch | `jwt_issuer` has a stray trailing slash, or names a different origin than the browser used. Zitadel's issuer is the bare origin — no path suffix. |
| Sign-in page 404s after clicking sign in | The v2 login UI is required but not running — see `LoginV2.Required` above. |
| `/auth/login` is a 404 | The API booted without a broker token or client id, so native sign-in did not mount (`api.log`: "native sign-in not configured"). Check `IDP_BROKER_TOKEN` in `secrets/dev.yaml` and that `_api`'s `config_secrets` names it; `forge env up dev` re-converges the identity and stores it. |
| IdP never comes up, no `.forge/idp/pat.txt` | Read `.forge/hostinfra/idp/zitadel.log` (host path) or `docker compose logs idp` (container path). Most often postgres was not reachable. |
| Public RPC works, authenticated one 401s with a valid token | The token is fine; check `jwt_audience` — a token minted for another application of the same issuer is correctly rejected. |
| `redirect_uri` mismatch AFTER typing a password | The broker's `oidc_redirect_uri` is not covered by what the identity step registered — confirm the frontend's `base_path` (KCL `forge.Frontend.base_path`, else the fallback in its next.config.ts) is what `.forge/identity/<name>.json` lists under `redirect_uris`. Nothing was redirected; the issuer rejected the server's auth request. |