Configure Logto OIDC (backend + frontend)

Auth is self-hosted Logto OIDC (Zitadel was migrated off). Login runs in the frontend via Auth.js (next-auth v5); the upstream access token never reaches the browser — it lives only on the encrypted server-side Auth.js JWT cookie, and core-gateway-consumer re-validates it on every single call by forwarding it as the gRPC bearer to core-identity /v1/auth/validate.

This page is the wiring recipe: set Logto up so the access token is a JWT (not opaque), point the frontend and core-identity at the same audience, and give core-identity a Management-API client so it can enrich profiles. For the why and the full flow diagram, see Identity & auth.

The one thing that must be right: request an API resource

Logto issues an opaque access token by default. core-identity can only validate a JWT against the JWKS — an opaque token makes it log Not enough segments. The fix is to register an API Resource in Logto and have the frontend request it (resource=…). The frontend’s AUTH_LOGTO_RESOURCE and the backend’s IDP_AUDIENCE are two separate env vars that must hold the same indicator string (e.g. your API host URL). Set one and forget the other and auth silently breaks. This is the Logto analog of Zitadel’s old Auth Token Type = JWT.

What you’ll set up

1. Stand up Logto (infra — out of scope here): the self-hosted deployment plus its Postgres DB. The end-to-end console spec lives in soundverse-saas-2.0/docs/auth-logto-setup.md. Note the four OIDC endpoints Logto exposes off its base (call it <endpoint>):

   Purpose	URL
   Issuer	<endpoint>/oidc
   JWKS	<endpoint>/oidc/jwks
   Userinfo	<endpoint>/oidc/me
   End-session	<endpoint>/oidc/session/end

   Take the JWKS URL from discovery

   Read the JWKS URL from the openid-configuration jwks_uri — it is <endpoint>/oidc/jwks. The commonly-guessed <endpoint>/.well-known/jwks.json is wrong for Logto.

2. Register an API Resource in Logto. Its indicator is the value both AUTH_LOGTO_RESOURCE (frontend) and IDP_AUDIENCE (backend) will hold. When the frontend requests this resource, the issued access token becomes a JWT whose aud equals the indicator.

3. Create the Traditional Web application the frontend uses. Register a redirect URI per Auth.js provider id — <origin>/api/auth/callback/logto, plus one for each social id (logto-google, logto-microsoft, logto-discord) — and a post-logout redirect URI for RP-initiated federated logout. Enable “Always issue refresh token” OFF; the frontend gets a refresh token via prompt=consent instead (see the trap below).

4. Create a Machine-to-Machine (M2M) application for profile enrichment and grant it the Logto Management API access role. core-identity uses its client-credentials to read GET {endpoint}/api/users/{sub} — this is how email/name/avatar/phone are resolved (the userinfo endpoint can’t be used; see the trap below).

5. Enable connectors and account linking. Turn on the Google / Microsoft / Discord social connectors and (for phone) the SMS connector, then enable each in the Sign-in Experience — direct_sign_in silently falls back to Logto’s own login page if the connector isn’t enabled there. Turn on automatic account linking so one human with a verified email/phone is one Logto user across many identities.

6. Wire the frontend env (soundverse-saas-2.0) — see the table below.

7. Wire the core-identity env — see the table below.

8. Verify. Sign in, then confirm the gateway accepts the bearer (a call to any /api/* returns data, not unauthenticated) and that a fresh identity.users row has a non-blank email. If the token is opaque you’ll see Not enough segments in core-identity logs — go back to steps 2 and 6.

Frontend config (soundverse-saas-2.0)

The Auth.js config is split so the gate can run at the edge: auth.config.ts is edge-safe (declares the Logto provider(s), scopes, and the authorized gate); auth.ts is the full Node instance with the jwt/session callbacks. It registers a base logto provider (for the phone-OTP button) plus one provider per social connector using direct_sign_in, all sharing the scope openid profile email phone offline_access.

Env var (name only)	Points at
AUTH_SECRET	Key that encrypts the server-side session JWT
AUTH_LOGTO_ID	The Traditional Web app’s client id
AUTH_LOGTO_SECRET	The Traditional Web app’s client secret
AUTH_LOGTO_ISSUER	<endpoint>/oidc (Auth.js discovers the rest)
AUTH_LOGTO_RESOURCE	The API-resource indicator — must equal backend IDP_AUDIENCE
REDIS_ADDR / REDIS_PASSWORD	Durable rotating-refresh-token store (see the double-spend trap)

`resource` must ride the token request too

Auth.js forwards authorization.params (including resource) only to the authorize step and ignores token.params — so the code exchange would still return Logto’s opaque token. The config injects resource into the token POST body via a customFetch shim (gated on a URLSearchParams body so only the token endpoint is touched). If you fork the provider setup, keep that shim.

Backend config (core-identity)

core-identity validates the JWT locally against the JWKS (app/core/auth/token.py) and provisions/enriches the user at /v1/auth/validate (app/routes/auth.py). Config lives in app/core/config.py.

Env var (name only)	Purpose	Legacy alias
IDP_ISSUER	OIDC issuer = <endpoint>/oidc	ZITADEL_OIDC_ISSUER
IDP_JWKS_URL	<endpoint>/oidc/jwks	ZITADEL_JWKS_URL
IDP_AUDIENCE	The API-resource indicator (the token’s aud) — must equal AUTH_LOGTO_RESOURCE	ZITADEL_OIDC_AUDIENCE
LOGTO_ENDPOINT	Logto base URL (host of both /oidc and /api)	—
LOGTO_M2M_CLIENT_ID	M2M app client id (Management API)	—
LOGTO_M2M_CLIENT_SECRET	M2M app client secret	—
LOGTO_MANAGEMENT_RESOURCE	Management-API indicator; defaults to https://default.logto.app/api for single-tenant self-host (a fixed indicator string, not a reachable URL)	—
LOGTO_TOKEN_URL	Token endpoint; defaults to {endpoint}/oidc/token	—
IDP_USERINFO_URL	Legacy OIDC userinfo enrichment (Zitadel rollback only; empty ⇒ skipped)	—

Each IDP_* setting still accepts its legacy ZITADEL_* name via AliasChoices, so an un-migrated docker-compose / ACA injection keeps working during a rollback. In staging/prod these are injected with the STAGING_/PROD_ prefix stripped — see Environment & service discovery.

Local (.env)

Set the IDP_* and LOGTO_* names above in each service’s .env. Keep names only — never commit real client secrets. For the shared-secret and prefix-injection pattern, see Configuring .env.

Staging / prod (ACA)

Set the org-level STAGING_/PROD_-prefixed variants (e.g. STAGING_IDP_AUDIENCE, STAGING_LOGTO_M2M_CLIENT_SECRET); the deploy template strips the prefix and injects them.

The traps that will actually bite you

`/oidc/me` rejects the resource-scoped JWT — enrich via the Management API

The access token the frontend holds is resource-scoped (aud = your API resource), and Logto’s /oidc/me only accepts a token with aud = Logto’s own OIDC audience. The two requirements — JWKS-validatable and userinfo-acceptable — are mutually exclusive for one token. Wire it to userinfo and every identity.users row lands with a NULL email/name. core-identity instead reads the profile from the Management API (M2M) in app/core/clients/management.py: GET {endpoint}/api/users/{sub}, mapping primaryEmail→email, avatar→image_url (not picture), primaryPhone→phone. This is why the LOGTO_M2M_* env is mandatory.

Logto signs with ES384, not RS256

Logto’s OIDC tokens are ES384 by default (Zitadel used RS256). The validator’s allow-list (_ALLOWED_ALGS) covers RS/ES/PS at 256/384/512 and never HS*/none (avoids alg-confusion). If you see The specified alg value is not allowed, the token alg isn’t in that list.

No refresh token without `prompt=consent` → sticky 401

Logto returns no refresh token for offline_access unless the login presents consent (prompt=consent) or the app’s non-OIDC-compliant “Always issue refresh token” toggle is on. With neither, the first token expiry sets error: RefreshAccessTokenError, the BFF treats it as unauthenticated, and the user is stuck on Please sign in to continue until re-login. The config keeps the toggle off and sends prompt=consent — the OIDC-correct fix.

Rotating refresh tokens double-spend across replicas

Logto rotates refresh tokens and its reuse-detection revokes the whole token family if a spent one is replayed. A per-process cache double-spends across ACA replicas / cold starts, so rotation is made durable in Redis (lib/auth/token-refresh.ts

• lib/auth/redis.ts): a distributed lock + rotated-token store keyed per subject, with an in-process fallback when Redis is unreachable. This is why the frontend also needs REDIS_ADDR / REDIS_PASSWORD. Watch the [auth] refresh-ok via=redis vs via=in-process log to confirm the store is reachable.

JIT provisioning at validate time

core-identity provisions just-in-time: any token that passes JWKS validation resolves to an identity.users row keyed on the token sub, and the first provision of a subject grants the signup token bundle via ingest.ensure_billing (SIGNUP_GRANT_TOKENS, default 1000). The gateway is provider-agnostic — it just forwards the bearer.

Blank-email JIT provisioning bug (live)

Known bug Because email/name come only from the Management API fetch, a subject whose GET /api/users/{sub} 404s (an M2M token, a deleted user, or a stale token replayed by a not-signed-out client) is still provisioned — with a blank email. A blank-email user can never converge-by-email, so it persists and is re-created every tick; it’s the seed of the library-split / vanish class. core-identity flags it via the identity.provision.no_email metric but does not yet refuse creation. If you see recurring blank-email rows, look for a stale background poller, not the real login. See core-identity.

Related

• Identity & auth — the full OIDC sequence and why the bearer stays server-side
• core-identity — the validate + JIT-provisioning service
• core-gateway-consumer — the trust boundary that re-validates every call
• Configuring .env — the shared-secret + prefix-injection pattern
• Environment & service discovery — STAGING_/PROD_ env injection
• Environment variable catalog — every fleet env-var name
• Troubleshooting — Not enough segments, sticky 401, and friends