Skip to main content
You will turn on passkeys and magic links beside passwords, see where Google or GitHub sign-in plugs in, publish one RPC and one page to signed-out visitors, and read the signed-in caller in a Go handler. Sign-in methods are a declaration in KCL. The app’s own login broker serves them, so the browser never talks to the identity provider and no token reaches JavaScript. Who may do what after sign-in is code you write. Forge proves who the caller is; the security model explains why the rules stay yours.

Before you begin

  • The shop project 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 forge inside the project. The exact-match publicExactPaths list 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
The prod render now hands the API one more value, 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
The dev identity provider takes the same declaration a hosted environment does. GitHub stays off until you create a separate dev OAuth app whose callback is the dev provider’s /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 admin@shop.localhost with password Password1! (from idp-steps.yaml). The session is an HttpOnly cookie, so keep a cookie jar:
terminal
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:
terminal
Open the mail UI from the 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:
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
Route guards scaffolded before forge v1.8 have only 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. middleware.GetUser returns the claims the auth interceptor validated, or unauthenticated when there are none:
internal/handlers/catalog/rpc_who_am_i.go
On a public RPC the handler gets no claims, even from a caller who sent a cookie. Use middleware.ClaimsFromContext there and check its ok.
8

Verify it works

The API reloads on save. Call each RPC with and without the session:
terminal
In a signed-out browser, /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, declare methods = ["password", "passkey"] and no social.
  • 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

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.
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.
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)