RFDs/0019

Passkeys, multi-factor authentication, and security settings

State
discussion
Authors
Darwin D Wu
Discussion
renga-dcim/renga#171
Labels
rengaaccountsauthenticationsecuritysoftware
Implemented
0%Checklist

Goal

Make Renga’s own sign-in strong enough that people are not asked to sign in again during normal work.

Today a Renga account signs in with a password or an emailed magic link, and user settings demand a sign-in within the last ten minutes ("sudo mode") before they open. That interrupts people constantly while protecting little: a password typed again proves no more than the first time.

This RFD adds passkeys, a time-based one-time password (TOTP) as a second factor, and recovery codes. It removes sudo mode, and keeps one narrow, fast check for the few changes that could take over an account.

It also collects Renga’s security settings in one place. Renga always enforces the protections that make a feature safe to exist at all. Anything beyond that is an organization setting that its owners choose to turn on, so nobody is asked to authenticate again, wait for a second person, or renew access unless their organization decided it should work that way.

Sign-in through an identity provider (RFD 15) is unchanged: that provider is responsible for its own multi-factor authentication. It meets an organization’s MFA requirement only when the provider is marked as enforcing MFA (MFA requirement).

Credentials

An account can hold:

  • Passkeys: any number of WebAuthn credentials, each with a name the person chooses, when it was added, and when it was last used. A passkey may be synced (for example through a password manager or platform keychain) or a hardware security key.

  • An authenticator app: one TOTP secret (RFC 6238, 30-second steps, six digits).

  • Recovery codes: ten single-use codes, shown once and stored hashed. Generating a new set invalidates the old one.

  • A password, which is optional once the account has a passkey.

An account has multi-factor authentication (MFA) when it holds a passkey or an authenticator app. Adding the first one generates recovery codes.

An account may be passwordless. A new account may register with only a passkey, and an existing account with a passkey may remove its password after the account re-check below. Removing the last passkey from a passwordless account is refused until a password is set, so an account always keeps at least one credential it can sign in with. A passwordless account has no password to reset: the reset email tells the person to sign in with a passkey or a recovery code instead, and the magic link still works as a first step but, as for any account with MFA, never signs the person in by itself.

Renga uses a pinned, reviewed WebAuthn library for registration and assertion verification, as RFD 15 does for OpenID Connect. Renga requires user verification on every passkey ceremony, so a passkey alone is two factors: the device and its PIN or biometric. It requests no attestation and accepts any authenticator, storing each credential’s ID, public key, signature counter, transports, and backup flags. The relying party ID is the deployment’s configured host.

Signing in

The sign-in page offers passkeys first, including browser autofill of saved passkeys, then email with a password or magic link.

  • A passkey signs the person in by itself.

  • A password or magic link is the first step for an account with MFA. Renga then asks for a passkey, an authenticator code, or a recovery code before it creates a session. The half-finished sign-in is bound to the browser, expires after five minutes, and grants nothing.

  • A password or magic link alone is enough for an account without MFA, as today, unless an organization requires MFA (below).

Authenticator codes are rate limited per account, and a code is never accepted twice: Renga records the last accepted time step. Every failure is recorded for the account’s security log.

Resetting a password by email only replaces the password. It never removes or bypasses the second step.

Removing sudo mode

Sudo mode goes away. The settings page opens without asking the person to sign in again, and no organization administration (members, roles, assignments, SCIM connections) asks for it.

Account re-check

A small set of changes could let someone who has stolen a session keep the account after the session ends:

  • changing the email address or password;

  • adding or removing a passkey or the authenticator app, or generating new recovery codes;

  • linking or unlinking an identity provider (RFD 15).

Each of these asks for one fresh check when the person saves it, in place, not a separate sign-in page. The check is a passkey assertion or an authenticator code; an account without MFA enters its password; an account that signs in only through a deployment OpenID Connect provider re-authenticates there with RFD 15's prompt=login and max_age rules. An organization-owned provider alone never authorizes an account-wide credential or identity change. A passing check covers that one change and any other on this list within the next five minutes, and nothing else.

An account with no enrolled MFA and no password uses a fresh email challenge to set its first password or add its first factor. The challenge is bound to that purpose, browser, and session, expires after five minutes, and authorizes no other account change. Renga delivers it to the account’s current email address; an identity provider’s email claim cannot satisfy it. Email never substitutes for an enrolled factor.

RFD 15's references to sudo mode mean this re-check.

Terminal step-up

RFD 13 step-up before opening a terminal becomes an organization opt-in, off by default. An organization that turns it on asks for a passkey or authenticator code within the last five minutes, or a fresh password from someone who has neither. Without it, terminals still require the organization and agent to enable them and a terminal grant, and record sessions unless the organization turns recording off (see Security settings). The account re-check never satisfies step-up, and step-up never satisfies the re-check.

Security settings

Always on

These are not settings, because without them a feature is unsafe or access cannot end:

  • Terminals and VM operations are disabled until both the agent enables them locally and the organization enables them (RFDs 13 and 14).

  • Privileged jobs need an approved installation key and a trusted target binding (RFD 13).

  • Explicit permissions such as terminal.open and vm.power are held only through an assignment someone made; no role includes them by default (RFD 17).

  • The account re-check above.

  • Access granted by an identity provider lasts only as long as the provider session, 12 hours by default and set per provider by the operator (RFD 15). This is how claim-mapped access ends when someone leaves the identity provider, unless the organization uses SCIM (RFD 16).

  • Every grant, setting change, terminal session, and VM operation is recorded in Activity, and every replay of a recording is logged.

Organization settings

Setting Default Defined in

Require multi-factor authentication for members

off

MFA requirement

Require step-up authentication before opening a terminal

off

Terminal step-up, RFD 13

Maximum validity of explicit permission grants

none

Grant validity

Record terminal sessions

on

Terminal recording, RFD 13

Recording retention

one year

RFD 13

Require a second operator for VM force_off and reset

off

RFD 14

Allow support access

off

Support access, RFD 22

Terminals and VM operations themselves are also organization settings, off by default, as RFDs 13 and 14 define.

MFA requirement

An organization owner may require MFA. A member can then open that organization only with a session whose sign-in used a second factor:

  • a passkey, or a password or magic link followed by Renga’s second step; or

  • an RFD 15 identity provider marked as enforcing MFA, as long as its ID token does not contradict the mark (below).

A member whose session does not qualify is asked for their passkey or authenticator code in place, without signing out, and a member without either is sent to enroll one first. Their other organizations are unaffected. So a member who signs in through a provider that is not marked adds a passkey to their Renga account once and confirms it after each provider sign-in.

Each identity provider has an enforces MFA mark, off by default. The operator sets it on deployment providers, and an organization owner sets it on the organization’s own providers; an owner cannot mark a deployment provider, because other organizations share it. The mark says the provider asks every person who signs in through it for a second factor, as a company’s own identity provider usually does, and setting or removing it is recorded in Activity. A github provider cannot be marked, because GitHub’s OAuth API says nothing about how the person signed in.

An organization provider’s mark satisfies only its owning organization’s MFA requirement. Only an operator-marked deployment provider can satisfy the requirement across organizations. The session keeps the provider ID, whether it is deployment- or organization-owned, and its owning organization as MFA evidence; Renga evaluates that evidence for the organization being opened rather than flattening it into an account-wide MFA flag.

When a marked provider’s ID token carries an amr claim, the sign-in counts only if amr contains mfa or a combination that the provider’s configuration explicitly approves as independent factors (RFC 8176). Counting methods is not enough: for example, pwd and kba are both knowledge factors. Any other present amr requires Renga’s local second step. Without amr, the mark alone decides. Removing the mark applies at each affected member’s next request, like any setting that adds a requirement.

Grant validity

An assignment that grants an explicit permission may have an expiry or none, like any other assignment. An organization may set a maximum validity, for example 30 days. With a maximum set, every new or renewed grant of an explicit permission must expire within it, and Renga proposes the maximum as the expiry when someone creates one.

Setting or lowering the maximum shortens existing grants that outlive it, so they end at the maximum measured from the moment the setting changed. It never ends a grant immediately, and running sessions continue until their own grant or lease ends.

Support access

A deployment’s operator may declare support identities (RFD 22): accounts from one hidden, MFA-enforcing identity provider that exist only to help diagnose problems. Allow support access appears in an organization’s security settings only when the deployment has declared them. It is off by default, and an owner may turn it on indefinitely or until a chosen time, with the description that it is for diagnostic purposes.

While it is on, every support identity holds the built-in read-only support role (RFD 17) in the organization, appears in the members list marked as support, and is recorded in Activity under its own name like any member. Support identities never hold other roles or explicit permissions, so they cannot change inventory, open terminals, operate VMs, export, or change settings.

Turning it off, or the expiry passing, ends the support memberships and their sessions in the organization immediately; this is the one setting whose change does end sessions, because its purpose is to end access. Unlike every other setting in this table, the operator can neither set a default for it nor lock it (RFD 22): the operator decides who its support people are, and only the owners decide whether they may enter.

Terminal recording

Recording is on by default, because a recording is the only record of what someone typed on a host. An organization that turns it off still records who opened each session, on which host, when, and for how long, and the session start still says whether the session is recorded. Turning recording off or on applies to sessions that start afterwards. Existing recordings keep their retention.

Changing settings

Changing a security setting requires the organization.manage permission (RFD 17), which only owners hold among the built-in roles. Each change is recorded in Activity with the actor, the before and after values, and a reason. The settings page shows each setting’s current value and who last changed it.

A setting that adds a requirement applies at each member’s next request to the organization; turning it on never signs anyone out or ends a running terminal session.

An operator can set deployment-wide defaults for these settings, and lock any of them to a value for the whole deployment or for one organization (RFD 22), except Allow support access (Support access). A locked setting shows as read-only, marked as set by the deployment, and owners cannot change it.

Amendments

  • RFD 1: live terminal access is disabled by default and requires authentication, authorization, agent-side policy, short per-session leases, and target-level access rules. Step-up authentication and recording are organization settings defined here.

  • RFD 13: step-up is an organization opt-in; terminal grants may expire, within the organization’s maximum if one is set; recording follows the organization’s setting.

  • RFD 14: VM operator grants follow the same validity rule as terminal grants.

  • RFD 15: each identity provider gains the enforces MFA mark, which only affects an organization’s MFA requirement. It does not change RFD 15's rule that provider re-authentication never satisfies terminal step-up.

  • RFD 17: an assignment that grants an explicit permission may expire, and must when the organization sets a maximum validity.

Recovery

A person who loses every passkey and their authenticator app signs in with a recovery code, which counts as the second step and is then spent. Renga prompts them to add a new factor. Completing primary authentication and spending the recovery code creates a five-minute recovery authorization bound to that browser and session. It permits only adding one replacement passkey or authenticator app, even when the spent code was the last one. After enrollment, the replacement factor supplies the ordinary re-check needed to remove lost factors or generate new recovery codes.

A person with no factors and no codes left cannot recover the account through Renga’s web interface. An operator can remove a user’s MFA with a release command, which records who ran it in the user’s security log; organization owners cannot, because they do not control the person’s other organizations.

Security log and notices

Each account has a security log of sign-ins, failed second steps, and every credential change, visible in settings. Adding or removing a passkey or the authenticator app, generating recovery codes, using a recovery code, and changing the email or password send a notice to the account’s email address, and an email change also notifies the old address.

Decisions

  1. Passwordless accounts. Allowed. An account with a passkey may remove its password, and a new account may register with only a passkey, as Credentials describes. A passkey-only account has no phishable or reusable secret, and recovery codes and the operator release command already cover a lost device.