Managing users

Managing users via config

As mentioned during Initialisation there is always at least one admin user. At the time you created your repo, you would see something like this in your config:

config:
  users:
    - name: bob
      desc: Bob the Builder
      pub: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIN6VzKY/HxjYdIjBnRi6Nq7/0ydsKpX3uk1gu/ywUDJj
  groups:
    admin:
      - bob

As you can see, bob is an admin. Let's assume we are building a cloud backend in a team and want to give some users the access to the required secrets for deployment. We can do so by adding some more users and a new group:

   users:
     - name: bob
       desc: Bob the Builder
       pub: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIN6VzKY/HxjYdIjBnRi6Nq7/0ydsKpX3uk1gu/ywUDJj
+    - name: alice
+      desc: Mrs. Wonderland
+      pub: github:alice
+    - name: peter
+      desc: Peter Lustig
+      pub: file://keys/peter.txt
   groups:
     admin:
       - bob
+    deployment:
+      - alice
+      - peter

We've used two new ways to fetch the keys:

• github:alice will use all configured public keys of the GitHub user alice (actually it's just the https://github.com/alice.keys). Many forges support API to fetch this information. You can also use gitlab: or codeberg:. This makes adding new users really easy, as you most likely already know the user name of your peer on your favorite forge. The public key will be fetched only once initially and the result is cached. Apart from the first time there is no online access required therefore.
• Peter on the other hand might not have an forge account. Maybe he also has an awful long RSA key that you don't want to put in the config verbatim. In this case you can just create a file in the repo and add it there. We recommend adding an exception to .gitignore if you want to push those public keys.

• The key of bob was deferred from the identity used during init. If you use the same public key for (e.g.) your GitHub account you can also write something like github:bob there.

Once we've changed the config we can this command, which should be familiar by now. This will then adjust the repository state accordingly:

$ sesam apply
- added user `alice`
- added user `peter`

Changing groups later works the same way.

Adding users and groups does not automatically give them access to secrets. We have to specify for each secret which groups have access to them (Reminder: the admin group has access always). Let's add them:

secrets:
  - path: some_password.txt
+   access:
+   - deployment

If you run sesam apply again, other users will have access. You have to commit (if you did not use --commit of course) and push it via git, of course. Then the others can pull the changes:

# on the laptop of alice:
$ git pull
$ sesam open

Managing users via CLI

You can have the same effect without editing configs:

# Add users like above:
$ sesam tell --user alice --recipient "github:alice"
$ sesam tell --user peter --recipient "file://keys/peter.txt"
# --access can be given several times:
$ sesam add some_password.txt --access deploy --access ops

Files automatically get re-encrypted ("sealed") after each operation. If you want to work in batches then add --no-seal and seal explicitly once at the end.

Removing users

Removing users is also something only admins can do:

$ sesam kill --user alice

This will remove alice from all the access, delete any group that is now empty and then re-encrypt all files.

Auxiliary operations

There are a couple of operations that are worth knowing they exist, but since they are not daily drivers we only briefly mentioned them. By now you should be able to guess what they do:

# List all users
sesam user list

# Change the groups a user is in
sesam user change-groups --user alice --group a --group b

# Add one or more recipients to an existing user
sesam user add-recipient --user alice -r "..." -r "..."

# Remove one or more recipients from an existing user.
sesam user remove-recipient --user alice -r "..."

# Regenerate the signing key of a user (seldomly useful)
sesam user regen-sign-key --user alice

# Rename an existing user.
sesam user rename ellisch alice