Users and login
managing snaps for administrators for Ubuntu Core developers for users
snapd answers three kinds of request. Some are open to every local user. Some need a logged-in snapd user or root or a polkit grant. Some need root. snap login creates a snapd user and stores a macaroon that authenticates later requests without sudo. On Ubuntu Core snap create-user also creates the Linux account and the first user makes the device managed.
On the map: administration district
01 Who is asking?
snapd's API has three access levels: open, authenticated and root. An authenticated request comes from a logged-in snapd user, from root, or from someone polkit has authorised. Reading snap configuration and logs is authenticated too. Root-level requests need root even after snap login.
You type snap list and it just works. You type snap install and you're refused, or a password dialog pops up. Same person, same terminal. What changed? The snap command asks snapd, and snapd wants to know who's asking. Most reads are open to any local user; a few, like snap get and snap logs, need the same as changes. Changing things, like install, connect or set, needs one of three: you've logged in to snapd, you're root, or polkit vouches for you after a password. Some requests, like quota groups and creating users, need root whatever else is true. Logging in opens the middle door, not the last one.
02 Logging in
snap login [<email>] authenticates to snapd and the store and saves a credential for your user. snap whoami prints the account's email or -; snap logout removes the snapd user and the saved credential.
Snap login asks for a password, but not the one you unlock the laptop with. It's your store account, and snapd asks the store to check it. Alice types snap login, her email, her password, and a two-factor code if she has one. Login itself changes things, so it needs sudo or a password dialog too. When it succeeds, snapd has a new user, and her home has a small credential file. From then on the snap command sends that credential along, and snap install works without sudo. snap whoami shows the account. Snap logout removes both. You don't have to log in, though. Sudo keeps working.
03 Two macaroons for administrators for Ubuntu Core developers
A snapd user in the state's auth entry has id, username, email, a snapd macaroon, and the store's store-macaroon and store-discharges. The client keeps the snapd macaroon in ~/.snap/auth.json (mode 0600) and sends it as Authorization: Macaroon root="…".
Login left two things behind that are easy to mix up, and both are called macaroons, which here just means signed tokens. In snapd's state, under auth, alice has an id, a username, an email, and two credentials. The first is snapd's own macaroon. The client keeps a copy in ~/.snap/auth.json, and sends it in the authorization header of every request. The second is the store's macaroon and its discharges. Snapd uses those when it talks to the store for her. Snapd checks its own one with a key kept in the same state entry. So if you write a client, send the local one.
04 Polkit is asked last for administrators for Ubuntu Core developers
For authenticated-level requests snapd accepts a valid login macaroon, then root, and asks the request's polkit action last. Polkit may prompt only when the client allows interaction. Root-level requests need uid 0 and do not use polkit.
Alice clicks install in a graphical store and a password dialog pops up. She types snap install in her terminal, where she's logged in, and nothing appears. Why the difference? Snapd has three ways to let the request through, and tries them in order. First, a macaroon from a login. Then, is the caller root? Only then polkit, if the request names a polkit action. Polkit comes last on purpose: it can interrupt a person, so snapd doesn't ask it when the answer is already yes. And polkit may only prompt if the client said it can interact. A script gets a plain refusal. Root-level requests skip all this.
05 The first user on the gateway for administrators for Ubuntu Core developers
snap create-user [--sudoer] <email> (Ubuntu Core only, root only) takes the username and SSH keys from the store account, adds the Linux user to the extrausers database and creates a snapd user for it. It prints created user "alice".
Now a different machine. The gateway came out of its box with no accounts. Nobody can log in, and that's deliberate. So who makes the first one? On Ubuntu Core, snapd can. Snap create user, with the --sudoer flag and an email, asks the store for that account's username and public ssh-keys. Snapd adds a Linux account with that name and those keys to the extrausers database, with sudo rights. It also makes a snapd user for her, already logged in. Now alice can SSH in. No keys on the account means no user. And on classic systems, snapd won't administer users at all.
06 Managed: after the first user, the door closes for administrators for Ubuntu Core developers
A device is managed when snapd has at least one user; snap managed prints the value. After that snap create-user answers cannot create user: device already managed unless --force-managed is given. users.create.automatic=false disables automatic creation from system-user assertions.
A device with no users has to accept its first one from somewhere. Once snapd's list of users isn't empty, the device is managed, and snap managed prints true. A snap login counts too. From then on, snap create user answers device already managed. Root can still add someone with the --force-managed flag. And the automatic path from assertions quietly does nothing on a managed device. users.create.automatic set to false turns it off.
07 How a user ends for administrators for Ubuntu Core developers
snap logout removes the snapd user only. snap remove-user <username> (Ubuntu Core, root) removes the Linux account and the snapd user. A user with an expiration is removed by snapd on its next regular pass in run mode after the date.
Giving someone access is half the job. The other half is how it ends, and there are three ways. Snap logout: snapd forgets the user and the credential file goes, but the Linux account stays. snap remove-user deletes the Linux account and then the snapd user, so alice can't SSH in. And a user can carry an expiration date. It's set through the API or comes from the assertion; the command has no flag for it. After the date, snapd removes the user itself, by force, on its next regular pass, so a little later than the date. If the minute matters, remove the user yourself.
08 Where to go from here
Roads: device assertions, the REST API, the store, identity assertions, configuration, install mode, and the administration district.
Users touch the store on one side and the device's identity on the other. Here's where each piece is explained in full. The device assertions deck covers the system-user assertion and the user who arrives on a USB stick. The REST API deck shows the daemon's side of the three levels. The store deck covers what a login is checked against, and identity assertions cover accounts. Configuration covers system options like users.create.automatic. Install mode covers a device's first boot, before it has any users. And the road back leads to the administration district.
Read more
Commands
| Command | Effect | Needs |
|---|---|---|
snap login [<email>] | authenticate to snapd and the store; prints Login successful | a logged-in user, root or a polkit grant |
snap logout | remove the snapd user and the saved credential | being logged in |
snap whoami | print email: <email> or email: - | nothing |
snap managed (hidden) | print true if snapd has any user, else false | nothing |
snap create-user [--json] [--sudoer] [--known] [--force-managed] <email> (hidden) | create a Linux user and a snapd user from a store account; prints created user "U" | root, Ubuntu Core |
snap remove-user <username> (hidden) | remove the Linux user and the snapd user; prints removed user "U" | root, Ubuntu Core |
Flags of create-user: --sudoer grants sudo; --known uses system-user assertions already on the device, each checked against the model first; --force-managed adds the user although the device is managed; --json prints the result as JSON.
Three kinds of user
| Name | What it is | Where it lives |
|---|---|---|
| store account | an account at login.ubuntu.com with a username and SSH keys | the store |
| snapd user | an entry in snapd's list of users, created by snap login or snap create-user | snapd's state, under auth |
| Linux user | an account on the device | the system's user database; the extrausers database on Ubuntu Core |
for administrators for Ubuntu Core developers
Access levels
| Level | Passes when | Otherwise | Examples |
|---|---|---|---|
| open | the request arrives on the snapd socket | snap list, snap aliases, snap quotas, snap warnings | |
| authenticated | a valid snapd macaroon, or uid 0, or the endpoint's polkit action is granted | 401 access denied | snap install, snap connect, snap set, snap get, snap logs, snap alias, snap okay |
| root | uid 0 | 403 access denied | snap set-quota, snap create-user, snap remove-user |
The checks run in that order: the login macaroon, then uid 0, then polkit. Polkit may show a prompt only when the client sends X-Allow-Interaction: true; the snap command does so when its standard input is a terminal. Requests that arrive on the socket used by snapctl are handled by a separate level and are not covered here.
| Polkit action | Used by |
|---|---|
io.snapcraft.snapd.login | login and logout |
io.snapcraft.snapd.manage | installing, refreshing and removing snaps; snapshots; acknowledging warnings |
io.snapcraft.snapd.manage-interfaces | connecting and disconnecting |
io.snapcraft.snapd.manage-configuration | reading and writing snap configuration |
io.snapcraft.snapd.manage-fde | full disk encryption operations |
| none | aliases (snap alias, unalias, prefer): root or a logged-in user only |
Every action asks for an administrator's password: auth_admin, and auth_admin_keep in an active session.
for administrators for Ubuntu Core developers
Files and state
| Place | Content |
|---|---|
~/.snap/auth.json | the client's copy of the credentials, mode 0600; written to the real user's home when run through sudo; SNAPD_AUTH_DATA_FILENAME overrides the path |
state, auth | last-id, users, device, macaroon-key |
a user in auth.users | id, username, email, macaroon, store-macaroon, store-discharges, optional expiration |
The header a client sends is Authorization: Macaroon root="<snapd macaroon>". SSH keys that came from the store are tagged in the user's authorized keys with a comment beginning # snapd {"origin":"store","email":...}.
for administrators for Ubuntu Core developers
API
| Endpoint | Level |
|---|---|
POST /v2/login | authenticated, polkit io.snapcraft.snapd.login |
POST /v2/logout | authenticated, polkit io.snapcraft.snapd.login |
GET /v2/users | root |
POST /v2/users, actions create and remove | root |
POST /v2/create-user (older form) | root |
Login body: username, email, password, otp. None of these endpoints creates a change; they answer at once. Login, logout and user creation are written to the security log.
Messages
| Message | When |
|---|---|
error: access denied (try with sudo) | an authenticated or root request from a user who is not root and has no other grant |
please use a valid email address. | login with something that is not an email |
Two-factor code: , Bad code. Try again: , Wrong again. Once more: | two-factor prompts |
not logged in | logout without a user |
system user administration via snapd is not allowed on this system | create-user or remove-user on classic |
cannot create user: device already managed | a user exists and --force-managed was not given |
no ssh keys found | the store account has no SSH keys |
cannot create user: expiration date must be set in the future | API create with a past date |
cannot create user: expiration date cannot be provided for known users | API create with known and a date |
need a username to remove, user "U" is not known | remove-user |
for administrators for Ubuntu Core developers
System options
| Option | Effect |
|---|---|
users.create.automatic | boolean, treated as true when unset; when false, automatic creation of users from system-user assertions does nothing |
users.lockout | true creates the marker file /etc/writable/account-lockout.enabled and false removes it; what reads the marker is outside snapd's source |
for administrators for Ubuntu Core developers
Expiration
A user created through the API may carry an expiration date; a user created from a system-user assertion takes it from the assertion. In run mode snapd removes expired users, by force, on its regular housekeeping pass, which runs every five minutes unless something triggers it sooner. The check of a request's macaroon does not look at the date, so until that pass removes the user, a request made with the expired user's macaroon is still accepted. This is recorded as a suspected bug. Do not rely on the date alone when the exact time matters.
Where the documentation differs
- The REST how-to shows a store macaroon and a discharge in the
Authorizationheader. The macaroon a client sends is snapd's own; a discharge is not needed for it. - The add-a-system-user how-to says no new user can be added to a managed system. It omits
--force-managedand that the automatic path returns nothing instead of failing.
Further reading
- API authentication and authorization: the three kinds of user and the access levels by name.
- Use the REST API: the
Authorizationheader andX-Allow-Interaction. See the difference above. - Add a system user:
auto-import.assertend to end, managed and unmanaged devices. - system-user: every header of the assertion.
- Use Ubuntu One SSH: the console-conf path that creates the first user from a store account.
- System options:
users.create.automaticandusers.lockout.
Roads from here
GETTING SNAPS
- The store — the store that the login is checked against
RUNNING SNAPS
- Configuration — system options such as users.create.automatic
ASSERTIONS · signed statements snapd trusts
- Assertions: devices — system-user assertions and the user from a USB stick
- Assertions: identity and store — accounts and the store's identity assertions
UBUNTU CORE · install and recovery
- Install mode — the first boot of a device that has no users yet
ADMINISTRATION · managing a system of snaps
- Aliases — back to the administration district
INSIDE SNAPD · the daemon itself
- The snapd REST API — the access checks and sockets and peer credentials in the daemon