Docs / User guide / Users and single sign-on

Users and single sign-on

This guide shows you how to add people, give them exactly the access they need per organization, server, deployment or trading account, and sign them in with single sign-on.

Updated 26 Oct 2026·Version 0.x
Command line only. Users and permissions are managed with the control plane’s administration commands. The dashboard has no user management page yet.

1. How access works

Access is denied unless a grant allows it. A grant gives one user a set of capabilities on one scope:

  • the whole organization;
  • one server, which covers its agent and its deployments;
  • one deployment;
  • one trading_account, for trading capabilities only.

Grants are checked on every request from the current records. A resource you cannot read answers as not found (404); one you can read but not change answers 403. Every refusal is written to the audit trail as authorization.denied.

Your identity provider only proves who someone is. Its roles and groups grant nothing in PerkBridge.

2. Bundles and capabilities

BUNDLECAPABILITIES
OPERATORView servers and deployments; create, start, stop and remove deployments; deliver broker credentials; add, set up and remove servers; download runtime images; acknowledge alerts; read notification channels, rules and the delivery log.
VIEWERagent:read and deployment:read only.
AUDITORThe viewer capabilities plus audit:read, the full audit trail.
TRADING_READ_ONLYaccount:read, market_data:read, orders:read.
TRADING_READ_WRITEAlso orders:create and positions:close. Accepted only on a trading account scope.

Some capabilities are in no bundle and are granted by name: trading:configure (symbols, routes, limits and risk rules), trading:halt, trading:tokens (Trading API tokens, organization or trading account scope only), deployment:failover (standby server and failover settings, needed on the deployment and on the standby server) and notification:manage (notification channels and rules, organization scope only).

Tip. A grant stores its capabilities when it is issued. When a release adds a capability to a bundle, older grants do not get it. If an operator sees “not allowed” for a newer action, issue a new grant.

3. Add users and grants

Run the administration commands on the control plane server, in /var/lib/nile/compose. The installer already created your first administrator with the OPERATOR bundle for the whole organization.

cd /var/lib/nile/compose # a password user: the password is read from standard input (12 to 256 characters) printf ‘%sn’ “$PASSWORD” | sudo docker compose exec -T control-plane /usr/local/bin/control-plane admin user create –org org-acme –email ops@example.com –name “Ops” –bundle OPERATOR –actor alice # read-only access to one server sudo docker compose exec -T control-plane /usr/local/bin/control-plane admin grant create –org org-acme –user usr-… –bundle VIEWER –scope server:srv-… –actor alice # revoke a grant, or disable a user (ends all their sessions) sudo docker compose exec -T control-plane /usr/local/bin/control-plane admin grant revoke –id grt-… –actor alice sudo docker compose exec -T control-plane /usr/local/bin/control-plane admin user disable –id usr-… –actor alice

A bundle given with user create applies to the whole organization. Use grant create with –scope (server:, deployment: or trading_account: plus the ID) for narrower access, and –capabilities with a comma-separated list instead of –bundle for single capabilities. –expires sets an expiry time. –actor names you in the audit trail.

Revoking a grant or disabling a user takes effect on the next request. Commands already signed for a server stay valid until they expire, at most 15 minutes.

4. Single sign-on

The installer can add a bundled Keycloak identity provider (–idp-host). Choose it at the first install: it cannot be added to an existing installation yet. The installer creates the nile realm and a nile-dashboard client that uses the authorization code flow with PKCE, and the sign-in pages use the Perkbridge Nile Connect theme. See Install PerkBridge.

Each single sign-on user exists in two places:

  1. Open the provider’s admin console through an SSH tunnel: ssh -L 8081:127.0.0.1:8081 root@nile.example.com, then http://localhost:8081/admin/. Sign in as nile-idp-admin with the first password from /var/lib/nile/idp-admin-password, and set a new one.
  2. Create the account in the nile realm, with a verified email address.
  3. Create the matching PerkBridge user with the same email and –sign-in sso (or both to allow a password too).

The user then chooses Sign in with Nile sign-in. To change that label, set NILE_IDP_DISPLAY_NAME in /var/lib/nile/compose/.env. At the first sign-in, the provider’s account is bound to the PerkBridge user. From then on only that provider account signs in as that user, even if its email changes. Sign-in never creates a user: unknown or unverified emails are refused and audited.

Two-factor sign-in comes from the provider. Keycloak offers one-time codes (TOTP), off by default, which you can require in the realm. Password accounts have no second factor. Only one provider per installation is supported, and the installer wires only the bundled one.

If the provider is down, password sign-in and existing sessions keep working; single sign-on fails until it is back.

5. Sessions and sensitive actions

A dashboard session lasts at most 8 hours and ends after 30 minutes without activity (the defaults). Password sign-in is rate-limited per address and per email.

Sensitive actions also need a recent sign-in, within 15 minutes by default. The dashboard asks you to confirm your password, or to sign in again with single sign-on, before:

  • starting a deployment with broker credentials, and turning on or using remembered credentials;
  • setting up a server, replacing its trusted host key, or removing a server;
  • creating a Trading API token;
  • changing a deployment’s failover settings, and arming or switching to a standby.

6. The audit trail

Sign-ins, sign-outs, re-authentications, user and grant changes, image approvals, deployment actions, credential deliveries and every refusal are recorded with who, what, when and a correlation ID. No password, token, key or credential is ever written.

Open Events and choose Audit trail. Organization-wide events such as sign-ins and grants, and source addresses, need audit:read. See Monitoring and alerts.

Was this page helpful?