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

▶ Watch this deck — 8 scenes, ~6 min

01 Who is asking?

USERS AND LOGIN alice · a terminalevery snap command is a requestsnapdopen: any local user$ snap list✓ works authenticated$ snap install photo-editorerror: access denied (try with sudo) also snap get, snap logs a logged-in snapd userroota polkit grantany one of these rootsudo, whoever you are$ snap set-quota ...$ snap create-user ... snap login moves you from the first lane to the second, not to the third
alice in a terminal sends requests to snapd in three lanes: snap list is open to any local user; snap get and snap logs are authenticated like changes; snap install is authenticated and is refused with error: access denied (try with sudo) unless alice is a logged-in snapd user, root or has a polkit grant; snap set-quota and snap create-user need root; snap login moves you from the first lane to the second, not to the third

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 $ snap login alice@example.comPersonal information is handled as per our privacy notice athttps://www.ubuntu.com/legal/dataprivacy/snap-store Password of "alice@example.com":Two-factor code:if the account has one login is itself a request thatchanges things: it needs sudoor a password dialog Login successfulyour credentiala snapd user, and a filesaved for your user;sent with every later command $ snap install photo-editor✓ no sudo$ snap whoamiemail: alice@example.com $ snap logout$ snap whoamiemail: - you don't have to log in: sudo keeps working · the account is a login.ubuntu.com account
A terminal: snap login alice@example.com prints the privacy notice, asks for the password and a two-factor code if the account has one, and prints Login successful; a credential is saved for alice; snap install photo-editor then works without sudo and snap whoami prints her email; snap logout removes the credential and snap whoami prints email: -

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

WHAT LOGIN STORED alice's home snapd state store authusers:id: 1username: aliceemail: alice@example.com macaroon: <snapd macaroon>store-macaroon: ...store-discharges: ... ~/.snap/auth.jsonmode 0600macaroon: <copy>a copy for the client Authorization: Macaroon root="..."sent with every request snapd uses thesewhen it talks to thestore for alice snapd checks its own macaroon with a key kept in the same state entry, and compares it with the copy on record
Three columns: alice's home, snapd state and the store. The auth entry in snapd's state holds alice's id, username, email, a snapd macaroon and the store macaroon with its discharges. A copy of the snapd macaroon sits in ~/.snap/auth.json, mode 0600, and goes to snapd in the header Authorization: Macaroon root=... on every request; snapd uses the store macaroon when it talks to the store for alice

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

THREE WAYS IN snapd alice in a terminallogged in to snapdmacaroon✓ recognised user: allowedpolkit is not consulted sudo snap installuid 0✓ root: allowed a graphical store appalice not logged inno macaroon, not rootpolkitio.snapcraft.snapd.manage password dialogan administrator's passwordthe app allows interaction;a script gets a plain refusal ✓ granted: allowed401 access denied root-level requests skip all of this: uid 0, or 403 · the full order, with sockets, is in the REST API deck
Three callers reach snapd: alice in a terminal, logged in, is allowed by her macaroon without asking polkit; sudo snap install is allowed as root; a graphical store app with no macaroon and not root makes snapd ask polkit for io.snapcraft.snapd.manage, which shows a password dialog because the app allows interaction, and then either grants the request or snapd answers 401 access denied

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

UBUNTU CORE snapdon the gateway $ sudo snap create-user --sudoer alice@example.comstore accountalice@example.comsnapd asks for the username and SSH keysusername: aliceSSH keys Linux account alicein the extrausers databaseSSH keys · sudo from --sudoer snapd user alicea local snapd macaroon in~/.snap/auth.json created user "alice"$ ssh alice@gateway✓ her store SSH key no SSH keys on the account: no ssh keys foundon classic: system user administration via snapd is not allowed on this system
On the gateway, sudo snap create-user --sudoer alice@example.com makes snapd ask the store for the account's username and SSH keys; snapd adds a Linux account alice to the extrausers database with the keys and sudo, and a snapd user alice with a local macaroon in her ~/.snap/auth.json; it prints created user alice and ssh alice@gateway works

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

MANAGED $ snap managedfalseno users a system-user assertionsnap create-usersnap loginfirst user$ snap managedtrue $ sudo snap create-user bob@example.comcannot create user: device already managed $ sudo snap create-user --force-managed bob@example.com✓the override, for whoever is already root users.create.automatic=falseswitches off automatic creation from assertions;on a managed device that path quietly does nothing
A timeline of the gateway. snap managed prints false until the first user arrives from snap create-user, a system-user assertion or snap login; then it prints true. A second snap create-user for bob fails with cannot create user: device already managed, and succeeds with --force-managed. users.create.automatic=false switches off automatic creation

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

ENDINGS Linux account alicesnapd user aliceLinux · snapd $ snap logoutLinuxsnapdsnapd forgets the user and the credential file goes; the Linux account stays $ sudo snap remove-user aliceremoved user "alice"Linuxsnapdthe Linux account first, then the snapd user expiration dateset through the API when the user is created,or taken from a system-user assertion;snap create-user has no flag for it snapd, in run modeon its regular passremoves expired users, by forceLinuxsnapd removal happens at snapd's next regular pass after the date, not at the exact moment:if the minute matters, remove the user yourself
alice has a Linux account and a snapd user. snap logout removes only the snapd user. sudo snap remove-user alice removes the Linux account, then the snapd user. A user can carry an expiration date, set through the API or by a system-user assertion; snapd in run mode removes expired users by force on its regular pass, a little after the date

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 Users and loginAssertions: devicessystem-user, a USB stick The REST APIthe daemon's side of the levels The storewhere a login is checked Assertions: identity and storeaccounts Configurationusers.create.automatic Install modefirst boot, no users yetAdministration districtback to the district
Roads from Users and login: device assertions, the REST API, the store, identity assertions, configuration, install mode and the administration district

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

CommandEffectNeeds
snap login [<email>]authenticate to snapd and the store; prints Login successfula logged-in user, root or a polkit grant
snap logoutremove the snapd user and the saved credentialbeing logged in
snap whoamiprint email: <email> or email: -nothing
snap managed (hidden)print true if snapd has any user, else falsenothing
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

NameWhat it isWhere it lives
store accountan account at login.ubuntu.com with a username and SSH keysthe store
snapd useran entry in snapd's list of users, created by snap login or snap create-usersnapd's state, under auth
Linux useran account on the devicethe system's user database; the extrausers database on Ubuntu Core

for administrators for Ubuntu Core developers

Access levels

LevelPasses whenOtherwiseExamples
openthe request arrives on the snapd socketsnap list, snap aliases, snap quotas, snap warnings
authenticateda valid snapd macaroon, or uid 0, or the endpoint's polkit action is granted401 access deniedsnap install, snap connect, snap set, snap get, snap logs, snap alias, snap okay
rootuid 0403 access deniedsnap 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 actionUsed by
io.snapcraft.snapd.loginlogin and logout
io.snapcraft.snapd.manageinstalling, refreshing and removing snaps; snapshots; acknowledging warnings
io.snapcraft.snapd.manage-interfacesconnecting and disconnecting
io.snapcraft.snapd.manage-configurationreading and writing snap configuration
io.snapcraft.snapd.manage-fdefull disk encryption operations
nonealiases (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

PlaceContent
~/.snap/auth.jsonthe 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, authlast-id, users, device, macaroon-key
a user in auth.usersid, 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

EndpointLevel
POST /v2/loginauthenticated, polkit io.snapcraft.snapd.login
POST /v2/logoutauthenticated, polkit io.snapcraft.snapd.login
GET /v2/usersroot
POST /v2/users, actions create and removeroot
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

MessageWhen
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 inlogout without a user
system user administration via snapd is not allowed on this systemcreate-user or remove-user on classic
cannot create user: device already manageda user exists and --force-managed was not given
no ssh keys foundthe store account has no SSH keys
cannot create user: expiration date must be set in the futureAPI create with a past date
cannot create user: expiration date cannot be provided for known usersAPI create with known and a date
need a username to remove, user "U" is not knownremove-user

for administrators for Ubuntu Core developers

System options

OptionEffect
users.create.automaticboolean, treated as true when unset; when false, automatic creation of users from system-user assertions does nothing
users.lockouttrue 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 Authorization header. 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-managed and that the automatic path returns nothing instead of failing.

Further reading

Roads from here

GETTING SNAPS

  • The store — the store that the login is checked against

RUNNING SNAPS

ASSERTIONS · signed statements snapd trusts

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