Before you begin
- The
shopproject from Build a Go and React app with Connect RPC. It already has the login broker (internal/app/login_broker.go), the dev identity provider and a dev mail catcher. - Forge v1.2 or later, run as
reliant forgeinside the project. The exact-matchpublicExactPathslist in the last step needs v1.8. - No account for the local steps. Docker is optional.
1
Declare the sign-in methods
Every environment imports
deploy/kcl/identity.k, so dev, staging and prod offer the same methods. methods takes "password", "passkey" and "magic_link"; social takes forge.IdentityGoogle and forge.IdentityGitHub, each with your own OAuth app.deploy/kcl/identity.k
client_secret names a secret in the environment’s store, never the value. Hosted environments don’t serve social or "magic_link" yet (see What this does not do). Passkeys bind to the sign-in host; set passkey_rp_id = "example.com" to keep them working across subdomains. signup stays "invite" unless you set "open" or "domain".2
Check that the broker serves them
terminal
IDP_LOGIN_POLICY, from which the broker mounts each method’s routes. The forgeconv-identity-methods rule in the full lint fails a declaration your broker doesn’t serve. A broker scaffolded before forge v1.1 serves none of them; reliant forge agent skill load migrations/v1.1.0/identity-v2 has the edit.3
Start the stack
terminal
/idps/callback and store its secret with reliant forge env secret set --env dev GITHUB_CLIENT_SECRET. The other methods work without it. Ask the API what the sign-in screen will offer, through the web dev server’s /_api proxy (use the web URL env up printed):terminal
4
Sign in with a password and with a magic link
The seeded dev user is A magic link is two calls. The request answers the same way for every address and sets a binding cookie, so the link works only in the browser that asked:Open the mail UI from the
admin@shop.localhost with password Password1! (from idp-steps.yaml). The session is an HttpOnly cookie, so keep a cookie jar:terminal
terminal
env up output. The message holds a link like http://localhost:3000/auth/magic?code=54234816. Redeem the code with the same jar:terminal
5
Add a passkey in the browser
A passkey ceremony needs an authenticator, so it runs in the browser. Forge scaffolds the account panel,
src/components/passkeys-panel.tsx, but doesn’t mount it: put it on an account page of your own and link that page from the user menu (src/components/session_nav.tsx shows where). Then sign in with a password, add a passkey there, sign out, and use Continue with passkey on the sign-in screen. In dev the relying party is localhost; hosted, it is the site’s host unless you set passkey_rp_id. The broker checks the browser’s origin before the identity provider sees the answer. The broker’s routes answer each stage of the ceremony:6
Choose what stays public
Every RPC requires a session unless its proto says otherwise. Publish the product list, and add an RPC that returns the caller:Route guards scaffolded before forge v1.8 have only
proto/services/catalog/v1/catalog.proto
NO_SIDE_EFFECTS marks WhoAmI as a read, so lint doesn’t ask it to declare an activity event.
Add WhoAmIRequest and a WhoAmIResponse with user_id, email and roles, then run reliant forge scaffold rpc catalog WhoAmI and reliant forge generate. pkg/middleware/procedures_gen.go now lists ListProducts as auth_required: false.auth_required: false publishes an RPC, not a page. The web route guard still sends signed-out visitors to sign in. List the page in src/lib/auth/route-guard.tsx:frontends/web/src/lib/auth/route-guard.tsx
publicPaths, which matches prefixes: adding "/products" there also opens /products/new and /products/edit, though their create and update calls still answer 401. The guard is scaffolded once and is yours, so upgrading forge does not replace it. Don’t list a section’s root in the prefix list to publish one page. Port the exact list first: reliant forge project upgrade --check shows the newer template’s route-guard.tsx, and you copy its publicExactPaths list and its RouteAccessContext.Provider into your own.7
Read the caller in a handler
Replace the scaffolded stub. On a public RPC the handler gets no claims, even from a caller who sent a cookie. Use
middleware.GetUser returns the claims the auth interceptor validated, or unauthenticated when there are none:internal/handlers/catalog/rpc_who_am_i.go
middleware.ClaimsFromContext there and check its ok.8
Verify it works
The API reloads on save. Call each RPC with and without the session:In a signed-out browser,
terminal
/products now renders the product list. Before the route-guard edit it redirected to /auth/sign-in?returnTo=%2Fproducts. Stop the stack with reliant forge env down dev.What this does not do
- No access rules. A signed-in caller can call every authenticated RPC. Roles and row filters are handler code: see Scope rows to their owner and Find unchecked endpoints.
- Hosted environments serve passwords and passkeys. The hosted control plane refuses social sign-in (“social sign-in is not available on this control plane yet”) and refuses magic links unless the identity declares
smtp. Social sign-in and magic links work in dev. To ship to staging or prod today, declaremethods = ["password", "passkey"]and nosocial. - No sign-up by default.
signup = "invite"means only owners, declared members and invited people get accounts."open"and"domain"need mail, and no session is issued until the address is verified. - The route guard is presentation. It decides what a signed-out visitor sees. The server checks the session on every RPC regardless.
Troubleshooting
[forgeconv-identity-methods] the identity declares methods "passkey" but internal/app/login_broker.go does not serve it
[forgeconv-identity-methods] the identity declares methods "passkey" but internal/app/login_broker.go does not serve it
Your broker reads the policy but doesn’t mount that method’s route, or predates the policy entirely. Apply the edits in
reliant forge agent skill load migrations/v1.1.0/identity-v2, or drop the method from identity.k. lint --conventions alone doesn’t run this rule; run the full reliant forge lint.identity: failed: the control plane refused the declaration
identity: failed: the control plane refused the declaration
reliant forge env status <env> shows why a hosted identity was refused, while env deploy keeps reporting “still applying” and exits 8. Remove the method it names (social, or magic links without smtp) and deploy a new release./bin/sh: 1: forge: not found in .forge/logs/dev/api.log
/bin/sh: 1: forge: not found in .forge/logs/dev/api.log
The scaffolded hot-reload config calls a bare
forge. Put a two-line forge script that runs exec reliant forge "$@" on your PATH, then run env up dev again.Next steps
Scope rows to their owner
Use the caller’s ID to filter every query
Security model
Fail-closed auth, the allow-list and who writes the rules
Find unchecked endpoints
List RPCs that never read the caller
Forge sign-in
How forge commands use your Reliant sign-in (not your app’s users)