Resources and permissions

This page helps you describe what your APIs protect, and give users, groups and clients permission to use it.

A resource is something you protect, usually an API, such as product-api. A permission is something a resource lets you do, such as read or delete-product. Together they make a scope, written resource:permission: product-api:read is the permission read on the resource product-api. That’s what your app asks for, and what the token it gets back carries.

Create a resource and its permissions

1. In the admin console, open Admin, Resources and permissions and click Create new.

2. Enter a Resource identifier, such as product-api, and a Description. Click Create.

3. Click Manage beside it and open Permissions. For each thing your API lets callers do, enter a Permission identifier, such as read, and a Permission description, and click Create permission. Click Save when the list is done.

4. Give each permission to whoever needs it:

   • a user, on the user’s Permissions tab, or on the resource’s Users with permission tab;
   • a group, on the group’s Permissions tab, or on the resource’s Groups with permission tab, and every member gets it;
   • a client, on the client’s Permissions tab, for a service that calls your API on its own behalf. The tab is available while Client credentials is on for the client.

   On a Permissions tab, choose the Resource and the Permission, click Grant permission, and click Save: until you save, nothing is granted.

Your app then asks for product-api:read in its scope, beside any OpenID Connect scopes, and your API checks the access token’s scope before it answers. See Scopes.

Identifiers

A resource identifier and a permission identifier are each 3 to 38 characters long. They start with a letter, end with a letter or digit, and use only letters, digits, - and _, with no -- or __. They’re case-sensitive, so the scope is too: product-api:read isn’t Product-API:read.

A description is at most 100 characters, and can’t contain < or >.

Two resources can’t share an identifier, and neither can two permissions of one resource.

A permission belongs to its resource

A permission identifier only means something on its own resource. Two resources can each have a permission called read, and they’re two different permissions: someone holding product-api:read can’t use reports-api:read. Grant each one separately.

So reusing short names like read, write and delete on every resource is normal, and it’s what makes the resource half of the scope matter. It goes for the authserver resource too: a manage permission on your own resource has nothing to do with authserver:manage.

Who holds a permission

A user holds the permissions given to them and those of every group they’re in. When your app signs a user in, the token carries only the permissions the user holds out of those it asked for. The others are left out without an error, unless none is left: then the request is refused with access_denied, as invalid_scope explains.

A client’s own permissions are for the client credentials flow alone, when the client gets a token for itself. A token a client gets for a user carries the user’s permissions, never the client’s.

Renaming and deleting

Renaming a resource or a permission changes its scope, so every app asking for the old one starts getting refused. The admin console asks you to confirm a renamed resource identifier.

Deleting a permission takes it away from every user, group and client that held it. Deleting a resource deletes all its permissions too, with the same effect.

The authserver resource

authserver is Goiabada’s own resource. Its permissions decide who can manage their own account and who can administer Goiabada, so it’s protected:

• its identifier can’t be changed, and it can’t be deleted;
• its built-in permissions can’t be renamed or deleted;
• its description can be changed, and you can add permissions of your own to it.

These are its built-in permissions, with the description each starts with:

Permission identifier	Description	Administrative
manage-account	View and update user account data for the current user	No
manage	Full administration, including administrators and administrative permissions	Yes
admin-read	Read-only access to all admin API endpoints	Yes
manage-users	Manage users and groups that are not administrators, and their non-administrative permissions	Yes
manage-clients	Manage OAuth2 clients that are not administrators	Yes
manage-settings	Manage system settings, except email and audit logging, and signing keys	Yes
browser-sessions	Read and write admin console browser sessions	Yes

Every user gets manage-account when they’re created. A user, group or client holding any of the six administrative ones is an administrator, and only authserver:manage can grant one, revoke one, or change its description. Administrators has the whole rule.

Caution

Granting an administrative permission is how you make someone an administrator. Grant one as carefully as you’d hand out the admin console’s password. Each grant and revocation leaves an administrative_permission_changed entry in the audit log you can alert on.

Next steps

ScopesHow your app asks for a permission, and what else it can ask for.

AdministratorsWho can administer Goiabada, and what each scope may do.