Identity and access¶
JANUS has two audiences and two browser surfaces:
- the WebUI (
/app), where administrators work with desired state and, on the platform scope, with administrative identities; - the Portal (
/portal), where an end user manages their own devices and retrieves a WireGuard configuration.
Both surfaces are clients of the Management API. Every authorization decision is made by the server, so hiding a control never grants or withholds authority — the boundary is the API.
This page covers the workflows an administrator and an end user actually perform: signing in safely, a second factor, recovery, sessions, API credentials, service principals, roles and bindings, the per-scope MFA policy, and the invitation-to-configuration journey.
Where each surface lives¶
| Task | Surface | Path |
|---|---|---|
| Your own password, factors, sessions | WebUI | /app/account |
| Administrative identities, their bindings and credentials | WebUI | /app/platform/principals |
| Every API credential, by identity | WebUI | /app/platform/credentials |
| Built-in roles and every binding | WebUI | /app/platform/roles |
| The per-scope second-factor requirement | WebUI | /app/platform/mfa-policy |
| Your own account security as an end user | Portal | /portal/security |
| Activate an invitation | Portal | /portal/invitation |
The platform identity-administration surfaces require the principal:admin
permission at platform scope, which the built-in platform_admin role carries.
A deployment-scoped administrator does not hold it and the API refuses the call.
Signing in¶
Administrators and end users both sign in with a local JANUS password. Password hashes are Argon2id. Authentication failures are uniform: an unknown account, a wrong password and a disabled account are indistinguishable, so the login surface cannot be used to enumerate accounts.
A first sign-in on a fresh installation uses the primary administrator created at setup; see Installation: Controller.
A second factor¶
A second factor strengthens authentication. It never grants authority: an administrator remains an administrator whether or not a factor is satisfied, and a factor grants nothing on its own.
Two kinds of factor are supported:
| Factor | Where | Notes |
|---|---|---|
| Authenticator app (TOTP) | /app/account, /portal/security |
A short code from a time-based one-time-password application |
| Passkey (WebAuthn) | /app/account, /portal/security |
Windows Hello, Touch ID, or a hardware security key |
Enrolling an authenticator app¶
- Open the account-security page (
/app/accountfor an administrator,/portal/securityfor an end user). - Choose Add authenticator app. A provisioning code and a manual-entry secret are displayed once.
- Scan or enter the secret into the authenticator application.
- Enter the current code to prove possession, and choose Confirm and activate. The factor is not active until a code has been accepted.
The shared secret is shown once and cannot be retrieved afterwards. Replacing a factor is a security-sensitive change of method: when a confirmed factor already exists, starting a new enrolment requires a recent sign-in (see Step-up).
Enrolling a passkey¶
A passkey's private key never leaves your device; only public credential material is stored on the server. The passkey cannot be phished or typed into the wrong site, because the browser binds it to the JANUS origin.
On the same account-security page, choose Add passkey, give it a name you will recognise, and follow your device's prompt. A registered passkey can be used either to sign in or to step up, and it can be removed from the same list.
Recovery codes¶
When an authenticator factor is first confirmed, JANUS issues a set of single-use recovery codes. They are shown once.
- Each code works exactly once, as a second factor.
- Generating a new set invalidates every previously issued code.
- Regenerating the set requires a recent sign-in.
Store the codes offline. A recovery code is a genuine second factor: it does not weaken the requirement, it makes it survivable.
When a step-up is asked for, enter a recovery code where the prompt offers it: the account-security page (the administrator WebUI) and the confirmation prompt in the self-service portal both accept a recovery code alongside the password and the authenticator code. Consuming a code signs nothing out and each code works once.
Sessions¶
The account-security page lists every session signed in as you, with when it was established, when it was last active, the source address, and its current strength. Current strength is distinct from how the session was originally established: a session that began with a password becomes second factor after a step-up.
Any session other than the current one can be revoked. Revoking takes effect immediately. Changing your password signs out your other sessions, and any privilege change to your account rotates its sessions, so a stale session never retains authority it no longer has.
Step-up (recent authentication)¶
Some operations are sensitive enough that authentication now matters, not just authentication at some point. Those operations require a recent sign-in — within a short window, or a fresh step-up.
| Operation | Requirement |
|---|---|
| Regenerating recovery codes | recent authentication |
| Removing a factor | recent authentication, and refused if a policy would be left unsatisfiable |
| Changing your password | recent authentication |
| Revoking one of your own sessions | recent authentication |
| Enrolling a device (Portal) | recent authentication |
| Retrieving a WireGuard configuration (Portal) | recent authentication |
You can reopen the window either by re-entering your password or by verifying a second factor. A principal with no second factor is never dead-ended: it re-authenticates with the factor it has.
Service principals and API credentials¶
A service principal is a non-human administrative identity for automation. It never signs in: it is created without any interactive credential, so no sign-in can ever resolve it. Its only credential is an API token.
The supported flow is:
- Principals & bindings (
/app/platform/principals) → Create principal, kind Service principal (integration). - Open the new principal and grant a role at a scope.
- In its API credentials section, choose Create credential: give it a label, optionally an expiry, and choose its permissions.
- Copy the secret — it is shown once and cannot be retrieved again.
- Use it as a bearer token in the
Authorization: Bearer <secret>header. - Revoke it when it is no longer needed; revocation takes effect immediately.
A credential's permissions inherit the principal's own bindings by default, and can be restricted to a subset. They can never exceed the principal's authority: a token that declares a permission its principal does not hold grants nothing. A service token cannot manage human account or MFA factors at all — the factor-management routes require an interactive browser session.
The API credentials page (/app/platform/credentials) lists every credential
in the installation by the identity that holds it, with its label, identifier,
creation and expiry, last use and state.
Roles and bindings¶
A role is a named collection of permissions; a binding grants a role to a principal at a scope. The built-in roles are fixed:
| Role | Intended for |
|---|---|
platform_admin |
platform-wide administration, including identities |
deployment_admin |
administration of one deployment |
deployment_viewer |
read-only visibility of one deployment |
self_service |
one linked end user's own devices, through the Portal |
Scopes are platform, a tenant, or a single deployment. In the WebUI you always choose a scope by name — a deployment or tenant is presented as the name you gave it, not as a raw identifier.
Grant a role from a principal's page (Roles & bindings → Grant a role), and
remove it from the same table. Removing a binding withdraws that authority
immediately, and the affected principal's sessions are rotated so no session
keeps authority it no longer has. The Roles & bindings page
(/app/platform/roles) shows every binding in the installation in one place.
The MFA policy¶
MFA is optional by default: no principal is locked out by an upgrade, and no
scope requires a second factor until an administrator says so. The policy is set
per scope on MFA policy (/app/platform/mfa-policy).
| Setting | Meaning |
|---|---|
| Scope | Where the requirement applies — platform, a tenant, or one deployment |
| Requirement | Whether a second factor is mandatory for principals authorized in that scope |
| Allowed factors | Which factors satisfy it. Empty accepts any supported factor; you can restrict it to authenticator app, passkey, or recovery code |
A requirement applies only within its own scope: a requirement on one deployment never affects another.
What happens to a principal that has no factor yet is deliberate, and is not a lock-out:
- a principal subject to the requirement cannot use its normal surfaces until it satisfies them;
- the account-security routes stay reachable, because they are how the
requirement is satisfied — an end user is taken to
/portal/securityand an administrator to/app/accountto set a factor up; - single-use recovery codes remain available;
- the host-local break-glass credential remains the operator's emergency path and is deliberately exempt from the requirement, so a lost factor cannot lock an operator out of recovery. Break-glass is disabled by default and can only be enabled from the Controller host; see Security model.
Removing a requirement never removes an enrolled factor — it only stops the requirement.
Invitations and activation¶
An administrator brings an end user in by issuing an invitation, which the recipient redeems themselves. The invitation is the whole of what the recipient needs: they choose their own password and never handle an administrator-issued credential.
administrator end user
| |
| create invitation |
| (deployment + user + device) |
|---------------------------------->|
| open /portal/invitation
| activate: choose a password
| satisfy MFA if the policy requires it
| enter the Portal
| manage their own device
| step up when a sensitive action needs it
| retrieve the WireGuard configuration
The invitation is bounded and single-use:
- it is scoped to one deployment and one intended user, and the recipient cannot choose the deployment, the user, the owner, the addresses, the gateway or the device name — all of them come from the invitation the administrator issued;
- it expires, and a replay is refused;
- it grants only the self-service role at that deployment. It cannot grant any administrative authority;
- activation does not bypass the MFA policy: a newly activated user subject to a requirement is held to it like any other;
- the invitation's bearer material is never echoed back and never stored in readable form.
Activating an account links the authenticated identity to the intended desired-state user for that deployment, so a redeemed invitation is the whole of what an ordinary end user needs.
End-user device enrollment and configuration¶
Inside the Portal, an end user manages exactly their own devices:
- My devices (
/portal/) lists them with their lifecycle state (enrolled, revoked, incomplete) and their observed activity, which are never conflated — "enrolled" is an access state and never claims a device is connected; - a device can be enrolled, renamed, revoked, restored or retired;
- retrieving its WireGuard configuration (and QR code) requires a recent sign-in.
The Portal never holds a device's private key. A configuration carries only what the user's own authorization compiled to, and a user can neither see nor request another user's device.
Worked example¶
Continuing the Northwind Logistics example from
Configuration: operator northwind runs deployment
northwind-prod, and end user alice has one device, alice-laptop.
1. Platform administrator signs in to the WebUI (/app) as the primary
administrator and opens /app/account to enrol an authenticator app.
2. On /app/platform/principals, the administrator creates a deployment
administrator, "northwind-ops", and grants it `deployment_admin` at the scope
of deployment northwind-prod. The scope is chosen by name.
3. On /app/platform/mfa-policy, the administrator sets a requirement for
deployment northwind-prod, allowing an authenticator app or a passkey.
Principals with a binding in northwind-prod must now satisfy it. Other
deployments are unaffected — including acme-prod on the same installation.
4. The deployment administrator issues an invitation for user alice and device
alice-laptop. Alice opens /portal/invitation, chooses her own password, and
is prompted to set up a second factor, because the policy requires one. She
enrols an authenticator app, then reaches /portal/.
5. Alice enrols alice-laptop and, when she retrieves its configuration, is asked
to confirm it is her (a recent sign-in). She imports the configuration into
her WireGuard client and reaches the resource her AccessPolicy authorizes.
6. When the audit review needs a machine identity, the platform administrator
creates a service principal "northwind-sync", grants it
`deployment_viewer` at northwind-prod, and issues an API credential whose
permissions inherit the principal. The secret is copied once; the credential
is revoked when the integration is retired.
Security notes¶
- Authorization is evaluated once, centrally, on the server. The WebUI and the Portal render what the API reports and decide nothing.
- Permissions are a closed enumeration and roles are code constants; a database row references a role but cannot redefine it.
- A password, a token secret, a session secret, a TOTP secret, a recovery code and a private key never reach a log, an audit event or a screenshot. One-time values are displayed exactly once.
- Denials do not disclose existence: a deployment-scoped resource answers
404, so "not found" and "not yours" are indistinguishable.