Docs · 1.0

Accounts, Tokens and Permissions

This chapter explains who can log in to keelOS and what they can do: the admin password, API tokens, web logins, the audit log, and logging in to keelOS with office accounts (keelAuth). Deploying the office account server is covered here too (the Accounts menu).

1. Who can get in

The keelOS web page and API have three ways in:

Whichever way you come in, you carry a set of permissions, and the page shows only what that set allows. Tabs you may not read do not appear; a read-only account can look but not change.

Note: The System tabs below appear according to permission: Tokens, Web logins and keelAuth login need token:admin; Audit log needs log:read; for the rest see the other chapters. If you cannot see any tab, the page says "This page needs an admin token".

2. Admin password

The admin password is this host's root password. The web password login, the host console and ssh all use it. Existing logins and tokens are not affected.

1. Open System → Tokens.
2. Click Set the admin password (Change the admin password when one exists; you must first enter the Current password).
3. Enter the New password and New password again, and click Save. The password must have at least 8 characters.

Note: The admin password always works, whatever keelAuth does. If keelAuth has a problem, or you lost a token, you can get in with it.

3. Tokens

A token is a key for programs: scripts, monitoring, kRDPclient and the keel manager all connect to the host with tokens. System → Tokens lists them all: ID, Name, Permissions, Made (when, and by whom), Last used (when, and from which address) and Expires.

Make a token

1. Click New token.
2. Name: if left empty, token-date-time is used.
3. Use: pick one. The description and permissions below change with it:

4. If you chose Other, tick the Permissions (at least one):

5. Only from these addresses (optional, CIDR): enter networks such as 192.168.1.0/24 (several are allowed); the token then works only from those addresses. Leave it empty for no limit.
6. Expires: never, or 1d, 7d, 30d, 365d.
7. Click Make the token.

The new token is shown only this once, so click Copy now. keel stores only its hash; if you lose it, you can only revoke it and make another. If the use is kRDPclient you also get a Connection string for kRDPclient (address, certificate and token together). Paste it into kRDPclient's add-host dialog, or click Open in kRDPclient. It too is shown only once.

Tokens limited to some VMs or tags are not on the web page yet. On the host use the command keel token create --vm … or --tag …, see The keel command line.

Revoke a token

Click Revoke on the token's row and confirm. The token stops working at once, and web logins made with it end too.

4. Web logins

System → Web logins lists the web logins that are valid now: Token (which token or account was used), From (address), Browser, Logged in and Last used. Yours is marked this browser. Click End on another row and that browser has to log in again immediately.

If you suspect a leaked password or token: first revoke the token or change the password, then end the suspicious logins here.

5. Audit log

System → Audit log records who did what and when: changing settings, power operations, creating and deleting VMs, making and revoking tokens, showing the keelAuth recovery key... Each entry has Time, Token (who), From (address), Action, Object and Result; failed results are shown in a conspicuous colour. It needs the log:read permission.

• The newest is at the top, 100 per page; page with Newer / Older.
• The search box (Search (token, address, action, object, result)) finds text.
• From / To select a time range; Today and Last 7 days fill it in with one click; Failures only keeps only failures; Clear removes all conditions.
• Times are shown in the time zone set on the host, see System: Maintenance, Time and Host Console.

6. Log in to keelOS with a keelAuth account

When the office has keelAuth (see §7), people can log in to keelOS with their own account, with no separate password or token.

1. First deploy a keelAuth in the Accounts menu. keel registers itself in keelAuth, and the login page gains a Log in with … button.
2. Open System → keelAuth login. Status shows On: the login page offers …. To stop people logging in with keelAuth for a while, click Turn off (and Turn on later).
3. Under Who may do what, set which level of permission each keelAuth group gets in keelOS. Click Change, then in the Groups and rights dialog Add a group, type the group name, choose the rights and Save:

4. If a group does not exist in keelAuth yet, the In keelAuth column of the table says missing; click Make the missing groups.
5. In keelAuth, put people into these groups. They click Log in with … on the keelOS login page and enter their own account on the keelAuth login page.

Things to know:

• Someone in several groups gets the highest permission; someone in none of them cannot log in.
• Permissions follow keelAuth within 15 minutes: remove someone from a group, disable or delete the account, and their login ends.
• The keelAuth login page opens on keelOS's own address, so no DNS record or certificate is needed for it.
• If keelAuth does not answer, the login page tells people to log in with the admin password.
• With several keelAuth servers, choose one with Which keelAuth. The keel's client in keelAuth row shows the registration state; if it says not registered, click Register again.

Note: When someone who logged in through keelAuth logs out, keelOS asks whether to log out of keelOS only (Log out of keel) or of keelAuth too (Log out of keelAuth too). On a shared computer choose the latter.

7. The Accounts menu: keelAuth

Accounts in the left menu is keelAuth: the office's account server, running in a VM on this host. Users and groups are managed in one place; devices and programs use the accounts through LDAP, web apps through single sign-on (OIDC), Wi-Fi and VPN through RADIUS. keelNAS also uses its users.

Deploy

With no keelAuth the page says there is no keelAuth on this host.

1. You need the keelAuth package. If it is not on the host, the button is Get keelAuth in the market; install it from the Market and come back.
2. Click Deploy a keelAuth and fill in: - Name. - keelAuth version. - The network, and the Address on the network: Fixed address (recommended: devices are told this address) (then fill in Address with prefix such as 192.168.1.30/24, Gateway, DNS servers), or DHCP (reserve the address on the router). Devices need keelAuth's address, so it should be fixed. With a fixed address, browsers and apps use the IP directly and need no DNS, but passkeys do not work; with DHCP the name must resolve. - Name (DNS): keelAuth answers to this name and it is on its certificate; add it to the office DNS. It is hard to change later. - Memory (leave empty for the default 0.5 GiB).
3. Click Deploy and start. keel creates the first administrator and shows keelAuth's first administrator with the User name, Password and Its page. The password is shown only this once, so write it down and click Written down.

The VM usually comes up in under a minute. The page says keelAuth is starting and shows it by itself when it is ready.

Everyday use

Once keelAuth is up, the Accounts page shows keelAuth's own admin page: add, delete and disable users, set groups, register LDAP devices, single sign-on apps and RADIUS clients (Wi-Fi access points, VPN), and upload the office's own certificate. keelOS has already logged you in, so you do not type a password; you need the first administrator's account only when you open keelAuth's own page directly in the office. For a bigger window click Open in a new window.

With several keelAuth servers you first see a list; click one to enter it, and come back with All keelAuth.

The page header also has these (they need host write permission):

• Recovery key: keelAuth encrypts the password hashes used for Wi-Fi and shares with a key that only this host can open. To restore a keelAuth backup on another host (or on this one after a reinstall) you need this recovery key. Click Show the recovery key (this is recorded in the audit log), then Copy or Download it. Keep it together with the backup, but not in the same place: whoever has both can read the password hashes.
• Rename, Delete. Delete removes the VM and all its disks together; all accounts are lost and cannot be recovered.
• When keelAuth does not answer, the page says why: keelAuth is shut down (click Start keelAuth), keelAuth is suspended (Resume keelAuth), the VM has been deleted, or keelAuth does not answer (Retry, or look at it under Virtual machines). Forget this keelAuth only makes this page stop managing it; the VM and the accounts stay.

Upgrade keelAuth

When a new version exists the card shows upgrade available and the page header has an Upgrade… button. keel shuts keelAuth down, swaps the system disk for the new version and starts it again. Accounts, groups, passwords, certificates and the address live on its data disk and do not change. Logins (LDAP, RADIUS, single sign-on) are unavailable for about a minute. If the new version does not come up properly, keel switches back to the old one by itself and tells you why.

The old version is kept for 7 days: click Roll back to return to it (users, groups and passwords changed after the upgrade are lost), or Keep this version to delete the old one.

8. Limits in 1.0

• Tokens can be limited only by permission and by source network; tokens limited to some VMs need the command line.
• keelOS has no user list of its own: for several people, use keelAuth groups, or one token per person.