Fangooth 25.04 > least-privilege API access

TrueNAS General
,
1

If I understand things, from 25.04 truenas switched from using an api key’s allowlist to limit endpoint access, to instead limiting access through the key’s user account? I can’t seem to get this working. I can access the api using a ‘fulladmin’ account (member of builtin_administrators) but accounts with lower permissions won’t let me to add an api key. The exception being if an account is added to the builtin_readonly_administrators group. But when I tested this it wouldn’t let me to run any commands.

What other user roles or permissions are available in Truenas that would let me:

  • Add an api key to the account
  • Provide a least privilege way for a user to send dataset lock and unlock endpoint commands and not much else?

What am I missing here? Any advice appreciated!

2

APIs are just for admins…

Can you expand on which APis coiuld not be run by an admin with read-only permsissions?

3

Minimally the account must have some privileges granted via the RBAC system for some group it is a member of. For example, you can make the account a member of the readonly administrators group and do this with the builtin RBAC privilege assigned to that group. The old allowlist required whitelisting individual methods (tightly coupled to actual backend details that hopefully no one wants to know), the new role-based system focuses on more coarse-grained privileges such as SNAPSHOT_READ.

4

In the docs it says the readonly admin cannot change any settings. I’m guessing that would include unlocking a dataset. The websocket API command is this:

“https://${TRUENAS_HOST}/api/v2.0/pool/dataset/unlock”

Under ‘Privileges’ for a group’s settings the help tip says:

image

image
image229×261 4.15 KB

The Sharing admin can create shares and datasets, might it have rights to unlock them also? I’ll give it a try in a while. As far as i’m aware, these are the only three roles that can possess an API token?

It seems to me the token allowlist functionality offered prior to 25.04 provided much greater security protection in the event of a compromised token. Again, if i’m not understanding how to use the RBAC system correctly please let me know. All the Advanced ACL options for a user given permissions on a dataset seem to be relating to the data itself. Rather than dataset management. That said, if you can’t add a token to the user anyway…

5

If it turns out the sharing administrator role can’t unlock datasets through the api then I guess full admin is all that’s on offer.

6

What is the API specifically that you are trying to call? Note that you are not limited to just the pre-defined privilege sets. This is a convenience feature. You can for instance do SHARING_ADMIN + (other roles). For example, create a privilege “MY_ADMIN” and assign it the roles, “SHARING_ADMIN” and “REPLICATION_ADMIN”. Members of groups assigned that role can now create shares and replication tasks.

The only thing currently that FULL_ADMIN gets you that you can’t get by adding on other roles is the ability to call into private APIs (which you shouldn’t be doing for obvious reasons) :slight_smile:

FYI, API documentation includes the role required to call an endpoint:
https://api.truenas.com/v25.10.0/api_methods_pool.dataset.unlock.html

7

Ok so pick the safest possible pre-defined API role and adding on the privilege DATASET_WRITE might just do the trick. I’ll have a play with that and see what happens. I suppose the readonly admin is still the best. The API endpoint in the command is: /api/v2.0/pool/dataset/unlock.

8

That said, SHARING_ADMIN grants DATASET_WRITE, so you can probably use that.

9

Yes, I notice it includes READONLY_ADMIN though so i’ll start there and maybe step up to sharing admin if necessary. That’s really useful, thank you.

10

You can even skip the READONLY_ADMIN and only grant POOL_READ, DATASET_WRITE if the only task is to query stuff related to pools and unlock datasets. This avoids granting the API user ability to list user accounts.

11

No luck so far. I removed the api user’s admin privs and added those in the image below. I also tried adding sharing_admin. The unlock script is failing with ‘curl received a 403 code’. If you’ve got a moment and want to take a look it’s quite small. This isn’t my repo btw. To me it just appears to query the dataset’s locked status then perform the unlock. The moment I drop the full admin role in, it unlocks:

image
image548×425 9.67 KB

12

I generally don’t debug user scripts. Why don’t you use our python API websocket client to do this? The REST API is scheduled to be deprecated.

13

Understandable! Thanks for your help.

14

If you need some examples of API client usage you can also look at our tests directory in the middleware repository

For example here is a test where encryption is being exercised.

Or look at the readme on the API client repo and piece something together like:

with Client(uri="ws://some.other.truenas/api/current") as c:
      c.call("auth.login_with_api_key", key)
      args = {"datasets": [{"name": "mypool/mydataset", "passphrase": "passphrase"}]}
      c.call("pool.dataset.unlock", "mypool/mydataset", args, job=True)
1 Like