Enabling a sign-in method for your residents
How to add an authentication provider in the Studio, choose its trust model, and understand why one switch on this screen needs its own permission.
Every way a resident can sign in — your own portal, a national digital identity, a one-time code sent by a vendor — is a row on this screen, not a line of code. Here's how to add one and set it up correctly.
1. Open City → Sign-in methods
Each row lists the provider's kind (OIDC, token handoff, SAML2, national digital identity, resident or vendor OTP), its trust model, its assurance level (A1–A4), and whether it may assert a resident's national ID. Click a row to open its detail panel.
2. Choose a trust model
If the provider issues a signed token, pick JWKS — the platform verifies the signature against keys the provider publishes, so a compromise of Kav's own store still can't mint a token as your city. Shared secret verifies a symmetric key instead; ticket exchange trusts the transport rather than a signature, for a provider whose token you redeem through a call-back rather than receive directly. The note beside the selector changes with your choice, because these are three different beliefs about what makes a token real, not three settings on the same idea.
A credential here is a vault key name and a fingerprint — never a value, at any privilege level. There's no field on this screen, and no field on the underlying GraphQL type, that could show you a secret once it's stored.
3. Set the assurance level
Every provider declares which of A1–A4 it proves. This is what a capability actually checks — a capability declaring it needs A2 will trigger a step-up sign-in through a stronger provider if a resident only signed in through an A1 one, automatically.
4. Think twice about "may assert national ID"
This switch lets the provider name any resident of your city and have the platform believe it — correct for your city's own authoritative portal, and wrong for almost anything else. It's gated on its own permission (tenancy.auth-provider.assert-national-id), separate from the general write permission every other field on this screen shares, so a role that can edit a provider's trust model can't necessarily turn this on.
There's no email-based identity linking anywhere in this screen, by design. Households share an address, vendor systems hold stale ones, and a matched email address is not proof of being the same person.
5. Read the refusal reference before you wire a portal
The "Sign-in refusals" drawer lists every code a token handoff can fail with — token.issuer_mismatch, provider.jwks_unavailable, identity.national_id_rejected, and 20 more — each mapped to the exact server-side message. A resident sees one generic sentence regardless of which check failed; your integrator sees this table.