Operator Sign-In

When RBAC is enabled, operators sign in through one or more authentication providers. ClawNex ships four sign-in methods that can be mixed per operator: passkeys (WebAuthn), GitHub OAuth, magic-link email, and a local password. The local password is the always-available break-glass login — it works even when every other provider is misconfigured or unreachable.

Sign-in providers layer on top of RBAC. Enable RBAC first (RBAC Setup) — with RBAC disabled, the dashboard is open to anyone on localhost and no sign-in occurs.

Providers at a Glance

Provider	What it is	Setup required
Local password	Username + password, stored as a bcrypt hash. The break-glass login that always works.	None — created with the first admin account
Passkey (WebAuthn)	Phishing-resistant device biometric or security key.	`AUTH_RP_ID`, `AUTH_EXPECTED_ORIGIN`
GitHub OAuth	Sign in with a linked GitHub account.	GitHub OAuth app + 3 env vars
Magic link	One-time link sent to the operator’s email.	Email transport (Emailit or SMTP)

Each operator’s enrolled providers are tracked individually (the auth_providers field on the account). Accounts created before v0.9.0 default to local until the operator enrolls additional methods from their profile.

Local Password (Break-Glass)

Always enabled. The first admin account (see RBAC Setup) is created with a username and password. Because it has no external dependency, the local password is the break-glass login: if GitHub is down, email is misconfigured, or a passkey is lost, an operator with a local password can still get in.

⚠️

This is a different feature from the shield Break-Glass procedure, which bypasses prompt scanning. The break-glass login never disables the shield.

Keep at least one admin with a local password set so you are never locked out.

Passkeys (WebAuthn)

Passkeys bind a login to a device authenticator (Touch ID, Windows Hello, a hardware security key). They are phishing-resistant — there is no shared secret to steal. Registration and authentication run through /api/auth/passkey/register/* and /api/auth/passkey/authenticate/*.

Set the relying-party identity so the browser scopes credentials to your host:

# .env / .env.local
AUTH_RP_ID=clawnex.example.com              # registrable domain, no scheme or port
AUTH_EXPECTED_ORIGIN=https://clawnex.example.com

Operators enroll a passkey from their profile after signing in with another method. AUTH_RP_ID must match the domain serving the dashboard, and AUTH_EXPECTED_ORIGIN must match the full origin (scheme + host + optional port) the browser sees, or registration is rejected.

GitHub OAuth

Create a GitHub OAuth app

In GitHub: Settings > Developer settings > OAuth Apps > New OAuth App. Set the authorization callback URL to https://clawnex.example.com/api/auth/github/callback.

Add the credentials

# .env / .env.local
GITHUB_OAUTH_CLIENT_ID=your-client-id
GITHUB_OAUTH_CLIENT_SECRET=your-client-secret
GITHUB_OAUTH_CALLBACK_URL=https://clawnex.example.com/api/auth/github/callback

Link the GitHub identity to an operator

An operator signs in once with another method, then links their GitHub account from their profile. Only linked GitHub identities can sign in — a GitHub login that maps to no operator is rejected.

⚠️

GITHUB_OAUTH_CALLBACK_URL must exactly match the callback URL registered in the GitHub OAuth app, including scheme and port.

Magic Link (Email)

Magic link sends a single-use, time-limited sign-in link to the operator’s email. ClawNex sends mail through Emailit or any SMTP server.

# .env / .env.local -- Emailit transport
EMAILIT_API_KEY=your-emailit-key
EMAILIT_FROM_EMAIL=clawnex@your-domain.com
MAGIC_LINK_EXPIRY_MINUTES=15
 
# ...or an SMTP transport instead of Emailit
SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_PASSWORD=your-smtp-password
SMTP_TLS=true

The operator must have an email address on their account. The link expires after MAGIC_LINK_EXPIRY_MINUTES (default 15) and can be used once. Send and completion run through /api/auth/magic-link/begin and /api/auth/magic-link/complete; you can verify delivery from Configuration > Authentication Methods.

Choosing Providers

Single operator / lab — the local password is enough.
Team — enable GitHub OAuth or magic link so people sign in with identities they already have, and add passkeys for phishing-resistant admin access.
Always — keep at least one local-password admin as break-glass.

Session timeout, concurrent-session limits, and progressive lockout apply to every provider — see RBAC & Roles.

RBAC & Roles Access Lists