5. Add permissions
Signed in or not is only the first question. The second is: may this person do this? SelfAuth answers that with permissions and roles.
- A permission is a name for one action. You make up the names. The convention is
thing.action. - A role is a group of permissions. Users have roles, and roles have permissions.
The notes app needs three permissions:
| Permission | Means | Who gets it |
|---|---|---|
notes.create | Save a note | Every user |
notes.view | Read your own notes | Every user |
notes.view_any | Read everyone's notes | Admins only |
The _any ending is a SelfAuth convention for "the same action, on everyone's data, not just your own".
Declare them
Open selfauth.config.json and find the authorization section. Change permissions and roles to this:
"permissions": ["notes.view", "notes.create", "notes.view_any"],
"roles": {
"user": ["notes.view", "notes.create"],
"admin": ["notes.view_any"]
},Every new account gets the user role (that's defaultRoles, just below). An administrator has the user role and the admin role, so admins can save and read their own notes too, plus read everyone's. You don't have to repeat notes.view and notes.create under admin.
The admin role also comes with SelfAuth's own permissions, like managing users and their roles. Those are built in, so they're not in your list.
Check you didn't misspell anything:
npx selfauth validateIf a role mentions a permission that isn't in the list, you'll see exactly which:
✗ config authorization.roles.admin.0: role 'admin' references undefined permission 'notes.viewany'Write them to the database
The server reads roles from the database, not the file, so after every change to roles or permissions, run the seed:
go run ./cmd/seedSynchronized roles: [admin user]Check it worked
Restart the server, so it reads the new configuration. If you're still signed in as Maya, ask who you are:
curl "${H[@]}" localhost:3000/auth/me{"session":{…},"user":{"id":"6e811164-…","email":"maya@example.com","emailVerified":true,"state":"active","roles":["user"],"permissions":["notes.create","notes.view"]}}Maya now has notes.create and notes.view. Her session is still valid after the restart, so she doesn't have to sign in again.
Make an administrator
Nobody can make themselves an admin through the API. The first administrator is made on the server, by someone with access to the database. Register a second account, Sam, and verify it the same way as in chapter 2, using a second cookie file so you stay signed in as Maya:
A=(-s -H 'Content-Type: application/json' -H 'X-SelfAuth-CSRF: 1' -b admin-jar -c admin-jar)
curl "${A[@]}" localhost:3000/auth/register \
-d '{"email":"sam@example.com","password":"another long password"}'
curl "${A[@]}" localhost:3000/auth/email/verify -d '{"token":"PASTE_SAMS_TOKEN"}'Then make Sam an admin:
go run ./cmd/create-admin sam@example.comsam@example.com is now an administrator.After that, other admins can be made through the admin API, with no command line needed.
Sign Sam in:
curl "${A[@]}" localhost:3000/auth/login \
-d '{"email":"sam@example.com","password":"another long password"}'{"user":{"id":"67bd0769-…","email":"sam@example.com","emailVerified":true,"state":"active","roles":["admin","user"],"permissions":["auth.audit.read","auth.roles.assign","auth.roles.manage","auth.sessions.manage","auth.users.manage","auth.users.read","notes.create","notes.view","notes.view_any"]}}Sam has both roles, and with them notes.view_any. You'll use Maya (H) and Sam (A) for the rest of the guide.
If something went wrong
- The permissions list is still empty. You didn't run
go run ./cmd/seed, or you didn't restart the server afterwards. No active account with that email.Sam has to be registered and verified beforecreate-adminworks.- The server panics with
unknown permissionwhen it starts. A route asks for a permission that isn't inselfauth.config.json. SelfAuth stops at startup rather than letting a typo lock everyone out quietly. role "user" is missing in the databasewhen the server starts. Rungo run ./cmd/seed.
Next: Add a table