OpenID Connect sign-in

Let people sign in to Renga with an identity provider their organization already runs, such as Google Workspace, Microsoft Entra ID, Okta, or Keycloak, and with GitHub. Today Renga only offers email with a password or a magic link, so every deployment keeps its own credentials and has to offboard people by hand.

Renga is a relying party only. It never issues tokens for other applications, and no provider is special to it: every provider, including whichever one an operator chooses as the only way in, is configuration. That configuration lives in Renga’s database and takes effect without a restart.

Providers exist at two levels:

Each provider has:

Renga uses a pinned, reviewed version of oidcc for oidc providers. The library supplies discovery, token verification, signing-key caching and rotation, and protocol request primitives. Renga still owns correct use of those primitives: it generates and binds state, nonce, and the PKCE verifier to each attempt, selects required validations, and separately enforces claims such as auth_time that the library does not age-check. The github kind is a small adapter on Req for the code exchange and GitHub’s user and email APIs, which no OpenID Connect library covers.

Renga uses the authorization code flow with PKCE, a per-attempt state, and for OpenID Connect a nonce. It validates the ID token’s signature against the issuer’s published keys, and its issuer, audience, expiry, and nonce, before trusting any claim. The callback runs in the browser pipeline and ends in the existing session creation, so a provider sign-in produces the same session, current_scope, and organization selection as a password sign-in.

Local session issuance, provider validation, and the account re-check (RFD 19) are three separate records of evidence. An ordinary provider callback, silent authorization, token refresh, or local session rotation never creates or refreshes re-check evidence merely because it issued a new Renga session.

A new user_identities table links a user to a provider subject: (provider_id, subject) is unique, and a user may have several identities. An OpenID Connect identity uses the token’s sub; a GitHub identity uses the stable numeric user ID, never the mutable login name.

Renga matches a returning sign-in by (provider_id, subject) only, never by email, because email addresses are reassigned and some providers let users change them freely.

An identity from the support source is always its own account, created on first sign-in and marked as a support identity. It is never linked to an existing account, no other provider can be linked to it, and it can hold only the built-in support role (RFD 17), granted by Renga while an organization allows support access (RFD 19); invitations, claim mappings, and SCIM never apply to it.

The first sign-in through a provider is resolved in this order:

An organization-created account that still has no global login email may start RFD 19's first-password or first-factor bootstrap by entering an address and proving mailbox control. Renga binds the challenge to that account, purpose, browser, and session and expires it after five minutes; the provider’s email claim neither chooses the address nor satisfies the challenge. Success may initialize only an empty global email and grants only RFD 19's limited bootstrap authorization, never a general account re-check. Renga refuses an address that belongs to another account and never uses this path to overwrite an existing global email or automatically link accounts.

Signed-in users can link and unlink providers from their settings, which requires the account re-check. The linking callback is bound to the initiating user and refuses a provider subject already linked to another user. Renga refuses to unlink a user’s last usable sign-in method under the current local sign-in and provider policy, or the last method capable of passing the account re-check.

GitHub cannot provide the fresh authentication evidence the re-check requires. The first release therefore does not allow GitHub to create a new user: a GitHub identity must be linked, after a re-check, to an existing account that already has a passkey, an authenticator app, a password, or a suitable OpenID Connect identity. A password remains usable for reauthentication even when local password sign-in is disabled.

A provider claim (for example groups, or a custom claim) can be mapped to organization memberships and roles. An operator sets the mapping for a deployment provider; an organization’s owners set it for their own organization’s provider. Renga records each mapped grant with the provider identity and mapping that issued it and a valid_until time; it does not flatten provider authority into an indefinite user membership. Authorization treats a mapped grant as a membership only while that source is valid.

On each successful validation with the issuing provider, Renga grants, updates, and renews the mapped grants present in the fresh claims and revokes ones that are no longer present. Signing in through a password, GitHub, or another OpenID Connect provider never extends them. Once a grant expires it provides no access until its own provider is successfully validated again. Unlinking its identity or removing its provider or mapping immediately invalidates its grants.

The first release permits at most one provider mapping to manage an organization, avoiding conflicting external authorities. A membership granted by hand takes precedence over a mapped grant for the same user and organization and is never changed or revoked by a mapping. Without a mapping, provider sign-in never touches memberships.

The mapping names organizations by slug and roles by Renga’s role names (owner, admin, member, viewer). A claim value that names an unknown organization or role is ignored and logged, not created. An organization provider’s mapping can name only its own organization.

A session created through a provider carries a lifetime, 12 hours by default and configurable per provider. An operator may set a longest allowed lifetime that organization providers cannot exceed. Renga’s remember-me cookie would otherwise keep a person signed in for weeks after their identity provider removed them.

When the lifetime has passed, Renga confirms the person with the provider again and recomputes claim-mapped memberships only from claims that provider defines as current. Renewal is provider-specific.

For OpenID Connect, provider configuration identifies the authoritative source for every mapped claim: a freshly validated ID token or UserInfo. Renga may use a refresh token in the background only when the resulting ID token or UserInfo response satisfies that provider’s freshness contract and contains every required claim. A successful token refresh alone is not revalidation and does not extend either the provider session or its mapped grants. Otherwise Renga starts authorization with prompt=none; if the provider does not support a silent result or requires interaction, Renga asks the person to sign in again.

For GitHub, Renga revalidates the stable numeric user ID through the user API with a usable access token, refreshing an expiring token where the GitHub OAuth application supports it. If that fails, it repeats the ordinary GitHub OAuth flow; it does not send the OpenID Connect-only prompt=none behavior.

Missing required claims, identity changes, expired or rejected credentials, and provider or network failures never silently extend expired authorization. Renga suspends the session and its mapped access until revalidation succeeds; a definitive refusal ends the session and shows the sign-in page.

Expiry is enforced on connected LiveViews as well as HTTP requests and navigations. Authenticated LiveViews schedule the provider deadline and recheck it before protected events and data delivery. Once it passes, the socket stops accepting mutations and receiving organization data until provider validation succeeds; keeping a page open never extends authorization.

The browser preserves its rendered form and unsaved input through reauthentication where feasible, but preserving a draft is a user-experience goal, not an exception to the authorization boundary. Membership changes take effect as soon as renewal completes; losing access to the current organization returns the person to organization selection rather than resuming the old socket scope.

Renga does not sweep memberships on a schedule. OpenID Connect UserInfo can refresh claims for a known subject while its access token is usable, but OpenID Connect has no standard provisioning feed that reports every offboarding or membership change. Request-driven revalidation provides the bounded lifetime; SCIM or back-channel events are future work. GitHub identities carry no group claims, so their renewal only confirms that the same account is still valid.

Two independent settings control local credentials:

Both are deployment settings, read from the environment at boot. The only runtime exception is the time-limited, operator-only local recovery override described above; it does not change registration.

If local sign-in is disabled and no deployment provider is active, a web node starts in fail-closed recovery mode instead of serving normal sign-in or protected routes. Health checks, release commands, and the short-lived provider test callback remain available so an operator can bootstrap or repair a provider. Leaving recovery mode requires atomically activating a tested deployment provider or establishing the temporary local recovery override.

The account re-check (RFD 19) and RFD 13 step-up are separate security levels. For the re-check, a user without a passkey, authenticator app, or password may reauthenticate through a linked deployment OpenID Connect provider. An organization-owned provider never authorizes an account-wide credential or identity change; an organization-created account with no other method first uses the email initialization and limited RFD 19 bootstrap above. Renga sends prompt=login and max_age, and binds the callback to the initiating local session, the re-check’s purpose, and the expected provider ID and subject; switching accounts fails the attempt. Renga accepts the result only after its normal ID-token checks and its own validation that auth_time is present, well formed, not in the future, and within the re-check window. Ordinary SSO, silent renewal, and GitHub OAuth never count as a re-check.

Where an organization requires RFD 13 step-up, it is a passkey or authenticator code when enrolled, otherwise a fresh password entry within five minutes. A recent auth_time alone says when authentication happened, not which factor or assurance level it used, so provider reauthentication does not satisfy terminal step-up. Supporting federated terminal step-up would require a later amendment that defines accepted acr and amr evidence per provider without weakening the enrolled-factor rule.

Signing out ends the Renga session. When the provider publishes an end_session_endpoint, an operator may enable RP-initiated logout so Renga also redirects there. Back-channel logout is out of scope for the first release.

Provider sign-in is for people in browsers. Agents keep RFD 3 intake keys and RFD 13 installation credentials; nothing in this RFD changes /api authentication.

Implementation checklist