Docs / Start here

The web console and sign-in accounts

This chapter covers the console: signing in, the difference between system and tenant administrators, finding your way around (the menu, the tenant picker, the search box and the themes), managing sign-in accounts, your own account page, two-factor sign-in, how long a sign-in lasts, and the change history.

Signing in

The console is at https://<server>/admin, for example https://pbx.example.com/admin. Plain http:// and the bare address both lead there.

1. Open the address in a browser. If the server still has its self-signed certificate, the browser warns that the connection is not private; continue to the page (see Names and certificates).
2. Enter your E-mail address and Password, and press Sign in.
3. If your account uses two-factor sign-in, enter the 6-digit Code from your authenticator app and press Continue. Back returns to the password.

The first account is the one you created in the first-boot setup (see Installing the server). Further accounts are made on the Sign-in accounts page.

What the messages mean:

There is no "forgot password" link. Another administrator gives a forgotten password a new one on Sign-in accounts (New password), or a server administrator runs onyx user password [email protected] on the server, which prints a new password.

System and tenant administrators

Every sign-in account has one role:

Only system administrators see these menu items: Tenants, Security, Call limits, Server settings and the whole Server section (Network, Storage, System & updates, Logs & diagnostics, Backup, Cluster).

Tenant administrators see the rest, for their own tenant only:

• Trunks (carriers) lists their tenant's own trunks, which they can edit, and trunks shared by all tenants, which they cannot.
• Sign-in accounts lists their tenant's accounts. They can create tenant administrators and phone users for their tenant, not system administrators.
• Change history, Call history, Reports and Billing show their tenant only.

System administrators belong to no tenant. Tenant administrators and phone users belong to exactly one.

Finding your way around

The menu on the left is grouped into Overview, Phone system, Calls, Connections, Administration and Server. The button next to the logo collapses the menu to icons (Collapse the menu to icons) and back (Show the menu labels); the browser remembers the choice. On a narrow screen, such as a phone, the Menu button opens the menu.

The header shows the server's name with engine running or engine not connected, and the Onyx Voice version. On the right are the theme switcher, the tenant picker (system administrators), your name and role, and the Sign out button. "no 2FA" after your role means your account does not use two-factor sign-in.

The box under the menu shows the server's certificate (HTTPS certificate, SELF-SIGNED or TRUSTED, and the days until it expires) and the server's addresses. At the bottom are the disk use, the versions of Onyx Voice and the engine, and how long each has been running.

The tenant picker

Most pages work on one tenant: Extensions & numbers, Phone numbers (DIDs), Outbound routes, Desk phones and the others. A system administrator chooses the tenant in the drop-down list in the header, which shows each tenant as "Name (code)". The choice stays for this browser tab. Manage on the Tenants page also switches to a tenant.

Tenant administrators have no picker: they always work on their own tenant.

If there is no tenant yet, the tenant pages say so and offer Create the first tenant (see Tenants (companies)).

The search box

Type an extension number, a name or an e-mail address into Find an extension, name or number... in the header and press Enter. The Extensions & numbers page opens with the list filtered to what matches, in the tenant you are working on. Click a row to open it.

Themes

The switcher in the header (and at the bottom of the menu) changes the console's look. The presets are Slate Ops (the default), Cut Obsidian, Swiss Precision, Tactical SOC and Daylight, a light theme. The choice is kept in this browser and applies to the portal too. It changes nothing for other people.

Sign-in accounts

Sign-in accounts lists who can sign in to the console or the portal: Person, Role, Tenant ("All" for system administrators), Last sign-in, 2FA (on or off) and Status (active or disabled).

Creating an account

1. Open Sign-in accounts and press New account.
2. Fill in Name and E-mail address. The e-mail address is what they sign in with; each address can have one account.
3. Choose the Role: System administrator (system administrators only), Tenant administrator or Phone user, and the Tenant (not for system administrators).
4. Password is filled in with a suggested password, such as Kf7m-Xq2p-Rt9w-Hb4n. Press Suggest for another one, or type your own of at least 10 characters.
5. Press Create account.

The console shows the address, the e-mail and the password once. Press Copy sign-in details to copy them for the person, then Done. The password is not shown again; they can change it after signing in.

For people with an extension, create the portal sign-in on the extension's page instead (User portal, Create portal sign-in). That links the account to the extension, so the portal shows their voicemail and calls. See Extensions and users.

Managing accounts

Each row (except your own, marked "You") has these buttons:

• New password makes a new password and shows it with a Copy button. The person is signed out everywhere until they use it.
• Reset 2FA (only when they use two-factor sign-in) turns their two-factor sign-in off, for someone who lost their phone and their recovery codes. They sign in with the password alone and can set it up again. It asks Lost their phone? Reset to confirm.
• Disable stops the account from signing in and signs it out at once. Enable lets it sign in again.
• Delete removes the account.

You cannot disable or delete your own account, or reset your own two-factor sign-in here; use your account page. When a tenant is switched off, its accounts cannot sign in either.

On the server, onyx user list, onyx user add, onyx user password, onyx user 2fa-reset and onyx user delete do the same (see Command line (onyx)).

Your account

Click your name or picture in the header to open Your account. It has two cards:

• Two-factor sign-in: see below.
• Password: enter the Current password and the New password (at least 10 characters), and press Change password. Your other sign-ins of this account, on other computers or browsers, are signed out; this one stays.

Two-factor sign-in

With two-factor sign-in, you sign in with a code from an authenticator app on your phone as well as your password, so a stolen password alone is not enough. Any app for time-based codes works, for example Microsoft Authenticator, Google Authenticator, 1Password or Authy. It is available to every account, including phone users in the portal.

Setting it up

1. Open Your account. The Two-factor sign-in card shows Off.
2. Press Set it up.
3. Scan the QR code with the authenticator app. If you cannot scan, press Copy the key and enter the key in the app as a time-based key. The QR code is made by the server itself; the key never goes to an outside service.
4. Type the 6-digit code the app shows into Code from the app and press Turn on.
5. The card shows 10 recovery codes. Press Copy the codes and keep them somewhere safe, such as a password manager or a printout. Then press I have saved them.

From now on, the sign-in asks for a code after the password. If the code is refused ("That code is not right (or was already used)"), check that the phone's clock is correct, and wait for the next code: each code works once.

Recovery codes

Each recovery code works once, in place of a code from the app: type it into Code when you sign in. After signing in with one, the console tells you how many are left. When fewer than three are left, the card on Your account warns you.

Changing it

The Two-factor sign-in card shows On and how many recovery codes are left. Each button needs the current Code from the app:

• New recovery codes replaces all recovery codes with 10 new ones.
• Move to a new phone starts the set-up again with a new key, for a new phone. The old phone's codes stop working once the new one is confirmed, and you get 10 new recovery codes.
• Turn off also needs your Password. It is not offered when the server requires two-factor sign-in for administrators.

If you lost the phone and the recovery codes, another administrator presses Reset 2FA on Sign-in accounts, or a server administrator runs onyx user 2fa-reset [email protected] on the server.

The keys are stored encrypted with a key file on the server (/etc/onyx-voice/secret.key), which backups include. A copy of the database alone does not reveal them.

Requiring it for administrators

A system administrator can make two-factor sign-in compulsory for every administrator (system and tenant administrators; phone users are not affected):

1. Open Security.
2. On the Two-factor sign-in card, tick Require it for administrators and press Save.

It takes effect within half a minute. An administrator without two-factor sign-in then sees a notice and the set-up card at their next sign-in, and can do nothing else in the console until it is set up. Administrators can no longer turn it off for themselves. The setting is security.require_2fa (admins or off).

Sessions and failed sign-ins

• A sign-in lasts until you press Sign out, until 8 hours pass without the browser using it, or at most 24 hours. Then you sign in again. A console page left open in the browser checks the server every minute and so keeps the sign-in alive until the 24 hours are up. Sign-ins survive restarts of the server.
• Changing your password signs out your other sign-ins. A new password from an administrator, disabling the account, or switching off its tenant signs it out everywhere at once.
• The second step of a two-factor sign-in must be finished within 5 minutes and allows 5 tries. After that, the console says "The sign-in took too long or had too many wrong codes. Sign in again."
• After 10 failed sign-ins for one account within 15 minutes, or 30 from one address, sign-in is refused for a while: "Too many failed sign-in attempts. Try again in 15 minutes."
• Failed sign-ins and wrong codes also count for intrusion prevention. By default, an address with 10 failures within 10 minutes is blocked at the firewall for 60 minutes, for the console and for SIP alike. Put your office and administrators' addresses on the Never block list on Security. See Security.
• If the console says "The request is missing its anti-forgery token. Reload the page and try again.", reload the page. This happens when a page was open from an earlier sign-in.

Change history

Change history lists who changed what, newest first: the latest 200 changes, with When, Who, What and, for system administrators, Tenant.

• Who is the e-mail address of the person who signed in to the console. Changes made with the onyx command on the server show the server account that ran it. Changes made from phones with feature codes (for example do not disturb or forwarding) show as "phone".
• What says what happened in words, for example "created extension 101".

Tenant administrators see their own tenant's changes. A system administrator sees the changes of the tenant chosen in the tenant picker.

Changes to server-wide settings (for example Server settings and the certificate) belong to no tenant, so they are not listed while a tenant is chosen. onyx has no command to list them either; they are kept in the database.