> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add sign-in with passkeys, magic links or social login

> Turn on passkeys, magic links and Google or GitHub sign-in by declaring them in KCL, then choose which RPCs and pages stay public and read the caller in Go.

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](https://docs.reliantlabs.io/deep-dives/security-model.md#2-you-write-the-access-rules-and-the-audit-finds-the-gaps) explains why the rules stay yours.

## Before you begin

* The `shop` project from [Build a Go and React app with Connect RPC](https://docs.reliantlabs.io/guides/forge/build-go-react-app-connect-rpc.md). 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.

```kcl deploy/kcl/identity.k theme={null}
IDENTITY = forge.ManagedIdentity {
    roles = [
        forge.IdentityRole {key = "admin", display_name = "Administrators"}
        forge.IdentityRole {key = "member", display_name = "Members"}
    ]
    methods = ["password", "passkey", "magic_link"]
    social = [forge.IdentityGitHub {
        client_id = "Iv1.0000000000000000"
        client_secret = forge.ManagedSecret {name = "GITHUB_CLIENT_SECRET"}
    }]
}
```

`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](#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**

```bash terminal theme={null}
reliant forge env render prod > /dev/null && reliant forge lint --quiet
```

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**

```bash terminal theme={null}
reliant forge env up dev
```

```text theme={null}
[up] identity identity: warning: social github: secret GITHUB_CLIENT_SECRET is not in the env's store, so github sign-in is off in this env. Create a DEV OAuth app (its callback is printed below), then `forge env secret set --env <env> GITHUB_CLIENT_SECRET`
[up] identity identity: Mail: http://localhost:8026
[up]   updated login policy "instance" (allowDomainDiscovery, allowExternalIdp, allowRegister, passwordlessType)
[up]   updated login policy "instance" (second factor SECOND_FACTOR_TYPE_OTP_EMAIL added)
[up] identity identity: wrote IDP_BASE, IDP_LOGIN_POLICY, IDP_LOGIN_URI, JWT_ISSUER, OIDC_REDIRECT_URI to secrets/dev.yaml
```

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

```bash terminal theme={null}
WEB=http://localhost:3000
curl -s $WEB/_api/auth/options
```

```json theme={null}
{"selfSignup":false,"signup":"invite","methods":["password","passkey","magic_link"],"social":[],"mail":true}
```

**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:

```bash terminal theme={null}
curl -s -c jar.txt -X POST $WEB/_api/auth/login -H 'Content-Type: application/json' -H "Origin: $WEB" \
  -d '{"email":"admin@shop.localhost","password":"Password1!"}'
```

```json theme={null}
{"authenticated":true,"subject":"400409236645543937"}
```

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:

```bash terminal theme={null}
curl -s -c mjar.txt -X POST $WEB/_api/auth/magic/request -H 'Content-Type: application/json' -H "Origin: $WEB" \
  -d '{"email":"admin@shop.localhost"}'
```

```json theme={null}
{"message":"If that address can sign in, a sign-in link is on its way."}
```

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:

```bash terminal theme={null}
curl -s -b mjar.txt -c mjar.txt -X POST $WEB/_api/auth/magic/consume -H 'Content-Type: application/json' -H "Origin: $WEB" \
  -d '{"code":"54234816"}'
```

```json theme={null}
{"authenticated":true,"subject":"400409236645543937"}
```

**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:

```text theme={null}
register/finish {"status":200,"body":"{\"registered\":true}"}
logout          {"status":200,"body":"{\"authenticated\":false}"}
passkey/finish  {"status":200,"body":"{\"authenticated\":true,\"subject\":\"400409236645543937\"}"}
```

**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:

```protobuf proto/services/catalog/v1/catalog.proto theme={null}
rpc ListProducts(ListProductsRequest) returns (ListProductsResponse) {
  option (forge.v1.method) = { auth_required: false };
}
// WhoAmI returns the signed-in caller.
rpc WhoAmI(WhoAmIRequest) returns (WhoAmIResponse) {
  option idempotency_level = NO_SIDE_EFFECTS;
  option (forge.v1.method) = { auth_required: true };
}
```

`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`:

```tsx frontends/web/src/lib/auth/route-guard.tsx theme={null}
const publicExactPaths: string[] = ["/products"];
```

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:

```go internal/handlers/catalog/rpc_who_am_i.go theme={null}
func (s *Service) WhoAmI(
	ctx context.Context,
	_ *connect.Request[pb.WhoAmIRequest],
) (*connect.Response[pb.WhoAmIResponse], error) {
	claims, err := middleware.GetUser(ctx)
	if err != nil {
		return nil, svcerr.Wrap(err)
	}
	return connect.NewResponse(&pb.WhoAmIResponse{
		UserId: claims.UserID,
		Email:  claims.Email,
		Roles:  claims.Roles,
	}), nil
}
```

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:

```bash terminal theme={null}
S=$WEB/_api/services.catalog.v1.CatalogService
curl -s -o /dev/null -w '%{http_code}\n' -X POST $S/ListProducts -H 'Content-Type: application/json' -d '{}'
curl -s -X POST $S/WhoAmI -H 'Content-Type: application/json' -d '{}'
curl -s -b jar.txt -X POST $S/WhoAmI -H 'Content-Type: application/json' -d '{}'
```

```text theme={null}
200
{"code":"unauthenticated","message":"missing Authorization header (procedure is not on the unauthenticated allow-list)"}
{"userId":"400409236645543937", "email":"admin@shop.localhost"}
```

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](https://docs.reliantlabs.io/guides/forge/scope-rows-to-owner.md) and [Find unchecked endpoints](https://docs.reliantlabs.io/guides/forge/find-endpoints-missing-auth-checks.md).
* **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

> [accordion] \[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`.

> [accordion] 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.

> [accordion] /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

> [card] [Scope rows to their owner](https://docs.reliantlabs.io/guides/forge/scope-rows-to-owner.md)
>
> Use the caller's ID to filter every query

> [card] [Security model](https://docs.reliantlabs.io/deep-dives/security-model.md)
>
> Fail-closed auth, the allow-list and who writes the rules

> [card] [Find unchecked endpoints](https://docs.reliantlabs.io/guides/forge/find-endpoints-missing-auth-checks.md)
>
> List RPCs that never read the caller

> [card] [Forge sign-in](https://docs.reliantlabs.io/forge/sign-in.md)
>
> How forge commands use your Reliant sign-in (not your app's users)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.