Documentation on API permissions?

C

chrullrich

New Member
Proxmox Subscriber
Jul 2, 2024
5
1
3
Hello,
is there some documentation on what exactly the "Check" lines in the API viewer (https://pve.proxmox.com/pve-docs/api-viewer/) mean? I can make sense of some of it, but I would like to be sure I understand it correctly.

Examples:
  • GET /access/domains/{realm}: Check: ["perm","/access/realm",["Realm.Allocate","Sys.Audit"],"any",1]
    I think this means either ("any of") Realm.Allocate or Sys.Audit on that path, but what is the 1 at the end? Surely not "any one of them" as opposed to "any two"?
  • POST /access/domains/{realm}/sync: Check: ["and",["perm","/access/realm/{realm}",["Realm.AllocateUser"]],["perm","/access/groups",["User.Modify"]]]
    One and the other.
  • GET /access/tfa/{userid}: Check: ["or",["userid-param","self"],["userid-group",["User.Modify","Sys.Audit"]]]
    Allowed when you are retrieving data on yourself, or you have the two permissions on a group that contains the userid, perhaps?
The last one, and the fact that the API viewer sometimes describes required permissions as explanatory text, makes me wonder if these "Check" expressions are merely pseudocode and there is no definite specification for them.

Thanks for any pointers.
 
https://git.proxmox.com/?p=pve-acce...665fcdef50ba80e319a;hb=refs/heads/master#l450

so you pretty much guessed correctly ;)

- 'and' and 'or' have the expected semantics
- 'any', '1' is actually 'any' => '1', as in, set the 'any' option to true, and yes, it refers to "any of these privileges"
- 'userid-param' means check the value of the userid parameter of the API call, with the value 'self' meaning it must match the authenticated user
- 'userid-group' is the most complicated one, it means you either have one of those privs on all groups and thus transitively all users, or you have it one of the groups of the user in the userid parameter (there's other special cases there as well that are not relevant for this particular API call)

note that not all checks are encodable in the schema, in which case there should be a human readable description giving you more information (e.g., sometimes checks might depend on existing guest config values, or only run if certain parameters are set).
 
chrullrich said:
Cześć,
Czy istnieje jakaś dokumentacja wyjaśniająca, co dokładnie oznaczają wiersze „Check” w przeglądarce API ( https://pve.proxmox.com/pve-docs/api-viewer/ )? Część z nich rozumiem, ale chciałbym mieć pewność, że dobrze je rozumiem.

Przykłady:
  • GET /access/domains/{realm}: Sprawdź: ["perm","/access/realm",["Realm.Allocate","Sys.Audit"],"any",1]
    Myślę, że oznacza to albo ("dowolny z") Realm.Allocate, albo Sys.Audit na tej ścieżce, ale czym jest to 1 na końcu? Na pewno nie "dowolny z nich", a raczej "dowolne dwa"?
  • POST /access/domains/{realm}/sync: Sprawdź: ["and",["perm","/access/realm/{realm}",["Realm.AllocateUser"]],["perm","/access/groups",["User.Modify"]]]
    Jedno i drugie.
  • GET /access/tfa/{userid}: Sprawdź: ["lub",["userid-param","self"],["userid-group",["User.Modify","Sys.Audit"]]]
    Dozwolone, gdy pobierasz dane o sobie lub masz dwa uprawnienia w grupie, która zawiera identyfikator użytkownika?
Ostatnia rzecz oraz fakt, że przeglądarka API czasami opisuje wymagane uprawnienia jako tekst objaśniający, sprawiają, że zastanawiam się, czy te wyrażenia „Sprawdź” nie są po prostu pseudokodem i nie ma dla nich konkretnej specyfikacji.

Dziękuję za wszelkie wskazówki.
Click to expand...
Hi, how did you grant the user permissions to access the API on the server side? I have an API connection to my PMG, but the ticket is empty. I don't think I have API user permissions. How do I do this?
 
fabian said:
https://git.proxmox.com/?p=pve-acce...665fcdef50ba80e319a;hb=refs/heads/master#l450

so you pretty much guessed correctly ;)

- 'and' and 'or' have the expected semantics
- 'any', '1' is actually 'any' => '1', as in, set the 'any' option to true, and yes, it refers to "any of these privileges"
- 'userid-param' means check the value of the userid parameter of the API call, with the value 'self' meaning it must match the authenticated user
- 'userid-group' is the most complicated one, it means you either have one of those privs on all groups and thus transitively all users, or you have it one of the groups of the user in the userid parameter (there's other special cases there as well that are not relevant for this particular API call)

note that not all checks are encodable in the schema, in which case there should be a human readable description giving you more information (e.g., sometimes checks might depend on existing guest config values, or only run if certain parameters are set).
Click to expand...
Hi, how did you grant the user permissions to access the API on the server side? I have an API connection to my PMG, but the ticket is empty. I don't think I have API user permissions. How do I do this?

AT
 
You must log in or register to reply here.
Top Bottom