src/PVE/API2/User.pm

   1 package PVE::API2::User;
   2
   3 use strict;
   4 use warnings;
   5
   6 use PVE::Exception qw(raise raise_perm_exc raise_param_exc);
   7 use PVE::Cluster qw (cfs_read_file cfs_write_file);
   8 use PVE::Tools qw(split_list extract_param);
   9 use PVE::JSONSchema qw(get_standard_option register_standard_option);
  10 use PVE::SafeSyslog;
  11
  12 use PVE::AccessControl;
  13 use PVE::Auth::Plugin;
  14 use PVE::TokenConfig;
  15
  16 use PVE::RESTHandler;
  17
  18 use base qw(PVE::RESTHandler);
  19
  20 register_standard_option('user-enable', {
  21     description => "Enable the account (default). You can set this to '0' to disable the account",
  22     type => 'boolean',
  23     optional => 1,
  24     default => 1,
  25 });
  26 register_standard_option('user-expire', {
  27     description => "Account expiration date (seconds since epoch). '0' means no expiration date.",
  28     type => 'integer',
  29     minimum => 0,
  30     optional => 1,
  31 });
  32 register_standard_option('user-firstname', { type => 'string', optional => 1 });
  33 register_standard_option('user-lastname', { type => 'string', optional => 1 });
  34 register_standard_option('user-email', { type => 'string', optional => 1, format => 'email-opt' });
  35 register_standard_option('user-comment', { type => 'string', optional => 1 });
  36 register_standard_option('user-keys', {
  37     description => "Keys for two factor auth (yubico).",
  38     type => 'string',
  39     optional => 1,
  40 });
  41 register_standard_option('group-list', {
  42     type => 'string', format => 'pve-groupid-list',
  43     optional => 1,
  44     completion => \&PVE::AccessControl::complete_group,
  45 });
  46 register_standard_option('token-subid', {
  47     type => 'string',
  48     pattern => $PVE::AccessControl::token_subid_regex,
  49     description => 'User-specific token identifier.',
  50 });
  51 register_standard_option('token-expire', {
  52     description => "API token expiration date (seconds since epoch). '0' means no expiration date.",
  53     type => 'integer',
  54     minimum => 0,
  55     optional => 1,
  56     default => 'same as user',
  57 });
  58 register_standard_option('token-privsep', {
  59     description => "Restrict API token privileges with separate ACLs (default), or give full privileges of corresponding user.",
  60     type => 'boolean',
  61     optional => 1,
  62     default => 1,
  63 });
  64 register_standard_option('token-comment', { type => 'string', optional => 1 });
  65 register_standard_option('token-info', {
  66     type => 'object',
  67     properties => {
  68         expire => get_standard_option('token-expire'),
  69         privsep => get_standard_option('token-privsep'),
  70         comment => get_standard_option('token-comment'),
  71     }
  72 });
  73
  74 my $token_info_extend = sub {
  75     my ($props) = @_;
  76
  77     my $obj = get_standard_option('token-info');
  78     my $base_props = $obj->{properties};
  79     $obj->{properties} = {};
  80
  81     foreach my $prop (keys %$base_props) {
  82         $obj->{properties}->{$prop} = $base_props->{$prop};
  83     }
  84
  85     foreach my $add_prop (keys %$props) {
  86         $obj->{properties}->{$add_prop} = $props->{$add_prop};
  87     }
  88
  89     return $obj;
  90 };
  91
  92 my $extract_user_data = sub {
  93     my ($data, $full) = @_;
  94
  95     my $res = {};
  96
  97     foreach my $prop (qw(enable expire firstname lastname email comment keys)) {
  98         $res->{$prop} = $data->{$prop} if defined($data->{$prop});
  99     }
 100
 101     return $res if !$full;
 102
 103     $res->{groups} = $data->{groups} ? [ keys %{$data->{groups}} ] : [];
 104     $res->{tokens} = $data->{tokens};
 105
 106     return $res;
 107 };
 108
 109 __PACKAGE__->register_method ({
 110     name => 'index',
 111     path => '',
 112     method => 'GET',
 113     description => "User index.",
 114     permissions => {
 115         description => "The returned list is restricted to users where you have 'User.Modify' or 'Sys.Audit' permissions on '/access/groups' or on a group the user belongs too. But it always includes the current (authenticated) user.",
 116         user => 'all',
 117     },
 118     protected => 1, # to access priv/tfa.cfg
 119     parameters => {
 120         additionalProperties => 0,
 121         properties => {
 122             enabled => {
 123                 type => 'boolean',
 124                 description => "Optional filter for enable property.",
 125                 optional => 1,
 126             },
 127             full => {
 128                 type => 'boolean',
 129                 description => "Include group and token information.",
 130                 optional => 1,
 131                 default => 0,
 132             }
 133         },
 134     },
 135     returns => {
 136         type => 'array',
 137         items => {
 138             type => "object",
 139             properties => {
 140                 userid => get_standard_option('userid-completed'),
 141                 enable => get_standard_option('user-enable'),
 142                 expire => get_standard_option('user-expire'),
 143                 firstname => get_standard_option('user-firstname'),
 144                 lastname => get_standard_option('user-lastname'),
 145                 email => get_standard_option('user-email'),
 146                 comment => get_standard_option('user-comment'),
 147                 keys => get_standard_option('user-keys'),
 148                 groups => get_standard_option('group-list'),
 149                 tokens => {
 150                     type => 'array',
 151                     optional => 1,
 152                     items => $token_info_extend->({
 153                         tokenid => get_standard_option('token-subid'),
 154                     }),
 155                 },
 156                 'realm-type' => {
 157                     type => 'string', format => 'pve-realm',
 158                     description => 'The type of the users realm',
 159                     optional => 1, # it should always be there, but we use conditional code below, so..
 160                 },
 161                 'totp-locked' => {
 162                     type => 'boolean',
 163                     optional => 1,
 164                     description => 'True if the user is currently locked out of TOTP factors.',
 165                 },
 166                 'tfa-locked-until' => {
 167                     type => 'integer',
 168                     optional => 1,
 169                     description =>
 170                         'Contains a timestamp until when a user is locked out of 2nd factors.',
 171                 },
 172             },
 173         },
 174         links => [ { rel => 'child', href => "{userid}" } ],
 175     },
 176     code => sub {
 177         my ($param) = @_;
 178
 179         my $rpcenv = PVE::RPCEnvironment::get();
 180         my $usercfg = $rpcenv->{user_cfg};
 181         my $authuser = $rpcenv->get_user();
 182
 183         my $domainscfg = cfs_read_file('domains.cfg');
 184         my $domainids = $domainscfg->{ids};
 185
 186         my $res = [];
 187
 188         my $privs = [ 'User.Modify', 'Sys.Audit' ];
 189         my $canUserMod = $rpcenv->check_any($authuser, "/access/groups", $privs, 1);
 190         my $groups = $rpcenv->filter_groups($authuser, $privs, 1);
 191         my $allowed_users = $rpcenv->group_member_join([keys %$groups]);
 192
 193         my $tfa_cfg = cfs_read_file('priv/tfa.cfg');
 194
 195         foreach my $user (sort keys %{$usercfg->{users}}) {
 196             if (!($canUserMod || $user eq $authuser)) {
 197                 next if !$allowed_users->{$user};
 198             }
 199
 200             my $entry = $extract_user_data->($usercfg->{users}->{$user}, $param->{full});
 201
 202             if (defined($param->{enabled})) {
 203                 next if $entry->{enable} && !$param->{enabled};
 204                 next if !$entry->{enable} && $param->{enabled};
 205             }
 206
 207             $entry->{groups} = join(',', @{$entry->{groups}}) if $entry->{groups};
 208
 209             if (defined(my $tokens = $entry->{tokens})) {
 210                 $entry->{tokens} = [
 211                     map { { tokenid => $_, %{$tokens->{$_}} } } sort keys %$tokens
 212                 ];
 213             }
 214
 215             if ($user =~ /($PVE::Auth::Plugin::realm_regex)$/) {
 216                 my $realm = $1;
 217                 $entry->{'realm-type'} = $domainids->{$realm}->{type} if exists $domainids->{$realm};
 218             }
 219
 220             $entry->{userid} = $user;
 221
 222             if (defined($tfa_cfg)) {
 223                 if (my $data = $tfa_cfg->tfa_lock_status($user)) {
 224                     for (qw(totp-locked tfa-locked-until)) {
 225                         $entry->{$_} = $data->{$_} if exists($data->{$_});
 226                     }
 227                 }
 228             }
 229
 230             push @$res, $entry;
 231         }
 232
 233         return $res;
 234     }});
 235
 236 __PACKAGE__->register_method ({
 237     name => 'create_user',
 238     protected => 1,
 239     path => '',
 240     method => 'POST',
 241     permissions => {
 242         description => "You need 'Realm.AllocateUser' on '/access/realm/<realm>' on the realm of user <userid>, and 'User.Modify' permissions to '/access/groups/<group>' for any group specified (or 'User.Modify' on '/access/groups' if you pass no groups.",
 243         check => [
 244             'and',
 245             [ 'userid-param', 'Realm.AllocateUser'],
 246             [ 'userid-group', ['User.Modify'], groups_param => 'create'],
 247         ],
 248     },
 249     description => "Create new user.",
 250     parameters => {
 251         additionalProperties => 0,
 252         properties => {
 253             userid => get_standard_option('userid-completed'),
 254             enable => get_standard_option('user-enable'),
 255             expire => get_standard_option('user-expire'),
 256             firstname => get_standard_option('user-firstname'),
 257             lastname => get_standard_option('user-lastname'),
 258             email => get_standard_option('user-email'),
 259             comment => get_standard_option('user-comment'),
 260             keys => get_standard_option('user-keys'),
 261             password => {
 262                 description => "Initial password.",
 263                 type => 'string',
 264                 optional => 1,
 265                 minLength => 5,
 266                 maxLength => 64
 267             },
 268             groups => get_standard_option('group-list'),
 269         },
 270     },
 271     returns => { type => 'null' },
 272     code => sub {
 273         my ($param) = @_;
 274
 275         PVE::AccessControl::lock_user_config(sub {
 276             my ($username, $ruid, $realm) = PVE::AccessControl::verify_username($param->{userid});
 277
 278             my $usercfg = cfs_read_file("user.cfg");
 279
 280             # ensure "user exists" check works for case insensitive realms
 281             $username = PVE::AccessControl::lookup_username($username, 1);
 282             die "user '$username' already exists\n" if $usercfg->{users}->{$username};
 283
 284             PVE::AccessControl::domain_set_password($realm, $ruid, $param->{password})
 285                 if defined($param->{password});
 286
 287             my $enable = defined($param->{enable}) ? $param->{enable} : 1;
 288             $usercfg->{users}->{$username} = { enable => $enable };
 289             $usercfg->{users}->{$username}->{expire} = $param->{expire} if $param->{expire};
 290
 291             if ($param->{groups}) {
 292                 foreach my $group (split_list($param->{groups})) {
 293                     if ($usercfg->{groups}->{$group}) {
 294                         PVE::AccessControl::add_user_group($username, $usercfg, $group);
 295                     } else {
 296                         die "no such group '$group'\n";
 297                     }
 298                 }
 299             }
 300
 301             $usercfg->{users}->{$username}->{firstname} = $param->{firstname} if $param->{firstname};
 302             $usercfg->{users}->{$username}->{lastname} = $param->{lastname} if $param->{lastname};
 303             $usercfg->{users}->{$username}->{email} = $param->{email} if $param->{email};
 304             $usercfg->{users}->{$username}->{comment} = $param->{comment} if $param->{comment};
 305             $usercfg->{users}->{$username}->{keys} = $param->{keys} if $param->{keys};
 306
 307             cfs_write_file("user.cfg", $usercfg);
 308         }, "create user failed");
 309
 310         return undef;
 311     }});
 312
 313 __PACKAGE__->register_method ({
 314     name => 'read_user',
 315     path => '{userid}',
 316     method => 'GET',
 317     description => "Get user configuration.",
 318     permissions => {
 319         check => ['userid-group', ['User.Modify', 'Sys.Audit']],
 320     },
 321     parameters => {
 322         additionalProperties => 0,
 323         properties => {
 324             userid => get_standard_option('userid-completed'),
 325         },
 326     },
 327     returns => {
 328         additionalProperties => 0,
 329         properties => {
 330             enable => get_standard_option('user-enable'),
 331             expire => get_standard_option('user-expire'),
 332             firstname => get_standard_option('user-firstname'),
 333             lastname => get_standard_option('user-lastname'),
 334             email => get_standard_option('user-email'),
 335             comment => get_standard_option('user-comment'),
 336             keys => get_standard_option('user-keys'),
 337             groups => {
 338                 type => 'array',
 339                 optional => 1,
 340                 items => {
 341                     type => 'string',
 342                     format => 'pve-groupid',
 343                 },
 344             },
 345             tokens => {
 346                 optional => 1,
 347                 type => 'object',
 348                 additionalProperties => get_standard_option('token-info'),
 349             },
 350         },
 351         type => "object"
 352     },
 353     code => sub {
 354         my ($param) = @_;
 355
 356         my ($username, undef, $domain) = PVE::AccessControl::verify_username($param->{userid});
 357
 358         my $usercfg = cfs_read_file("user.cfg");
 359
 360         my $data = PVE::AccessControl::check_user_exist($usercfg, $username);
 361
 362         return &$extract_user_data($data, 1);
 363     }});
 364
 365 __PACKAGE__->register_method ({
 366     name => 'update_user',
 367     protected => 1,
 368     path => '{userid}',
 369     method => 'PUT',
 370     permissions => {
 371         check => ['userid-group', ['User.Modify'], groups_param => 'update' ],
 372     },
 373     description => "Update user configuration.",
 374     parameters => {
 375         additionalProperties => 0,
 376         properties => {
 377             userid => get_standard_option('userid-completed'),
 378             enable => get_standard_option('user-enable'),
 379             expire => get_standard_option('user-expire'),
 380             firstname => get_standard_option('user-firstname'),
 381             lastname => get_standard_option('user-lastname'),
 382             email => get_standard_option('user-email'),
 383             comment => get_standard_option('user-comment'),
 384             keys => get_standard_option('user-keys'),
 385             groups => get_standard_option('group-list'),
 386             append => {
 387                 type => 'boolean',
 388                 optional => 1,
 389                 requires => 'groups',
 390             },
 391         },
 392     },
 393     returns => { type => 'null' },
 394     code => sub {
 395         my ($param) = @_;
 396
 397         my ($username, $ruid, $realm) = PVE::AccessControl::verify_username($param->{userid});
 398
 399         PVE::AccessControl::lock_user_config(sub {
 400             my $usercfg = cfs_read_file("user.cfg");
 401
 402             PVE::AccessControl::check_user_exist($usercfg, $username);
 403
 404             $usercfg->{users}->{$username}->{enable} = $param->{enable} if defined($param->{enable});
 405             $usercfg->{users}->{$username}->{expire} = $param->{expire} if defined($param->{expire});
 406
 407             PVE::AccessControl::delete_user_group($username, $usercfg)
 408                 if (!$param->{append} && defined($param->{groups}));
 409
 410             if ($param->{groups}) {
 411                 foreach my $group (split_list($param->{groups})) {
 412                     if ($usercfg->{groups}->{$group}) {
 413                         PVE::AccessControl::add_user_group($username, $usercfg, $group);
 414                     } else {
 415                         die "no such group '$group'\n";
 416                     }
 417                 }
 418             }
 419
 420             $usercfg->{users}->{$username}->{firstname} = $param->{firstname} if defined($param->{firstname});
 421             $usercfg->{users}->{$username}->{lastname} = $param->{lastname} if defined($param->{lastname});
 422             $usercfg->{users}->{$username}->{email} = $param->{email} if defined($param->{email});
 423             $usercfg->{users}->{$username}->{comment} = $param->{comment} if defined($param->{comment});
 424             $usercfg->{users}->{$username}->{keys} = $param->{keys} if defined($param->{keys});
 425
 426             cfs_write_file("user.cfg", $usercfg);
 427         }, "update user failed");
 428
 429         return undef;
 430     }});
 431
 432 __PACKAGE__->register_method ({
 433     name => 'delete_user',
 434     protected => 1,
 435     path => '{userid}',
 436     method => 'DELETE',
 437     description => "Delete user.",
 438     permissions => {
 439         check => [ 'and',
 440             [ 'userid-param', 'Realm.AllocateUser'],
 441             [ 'userid-group', ['User.Modify']],
 442         ],
 443     },
 444     parameters => {
 445         additionalProperties => 0,
 446         properties => {
 447             userid => get_standard_option('userid-completed'),
 448         }
 449     },
 450     returns => { type => 'null' },
 451     code => sub {
 452         my ($param) = @_;
 453
 454         my $rpcenv = PVE::RPCEnvironment::get();
 455         my $authuser = $rpcenv->get_user();
 456
 457         my ($userid, $ruid, $realm) = PVE::AccessControl::verify_username($param->{userid});
 458
 459         PVE::AccessControl::lock_user_config(sub {
 460             my $usercfg = cfs_read_file("user.cfg");
 461
 462             # NOTE: disable the user first (transaction like), so if (e.g.) we fail in the middle of
 463             # TFA deletion the user will be still disabled and not just without TFA protection.
 464             $usercfg->{users}->{$userid}->{enable} = 0;
 465             cfs_write_file("user.cfg", $usercfg);
 466
 467             my $domain_cfg = cfs_read_file('domains.cfg');
 468             if (my $cfg = $domain_cfg->{ids}->{$realm}) {
 469                 my $plugin = PVE::Auth::Plugin->lookup($cfg->{type});
 470                 $plugin->delete_user($cfg, $realm, $ruid);
 471             }
 472
 473             # Remove user from cache before removing the TFA entry so realms with TFA-enforcement
 474             # know that it's OK to drop any TFA entry in that case.
 475             delete $usercfg->{users}->{$userid};
 476
 477             my $partial_deletion = '';
 478             eval {
 479                 PVE::AccessControl::user_remove_tfa($userid);
 480                 $partial_deletion = ' - but deleted related TFA';
 481
 482                 PVE::AccessControl::delete_user_group($userid, $usercfg);
 483                 $partial_deletion .= ', Groups';
 484                 PVE::AccessControl::delete_user_acl($userid, $usercfg);
 485                 $partial_deletion .= ', ACLs';
 486
 487                 cfs_write_file("user.cfg", $usercfg);
 488             };
 489             die "$@$partial_deletion\n" if $@;
 490         }, "delete user failed");
 491
 492         return undef;
 493     }});
 494
 495 __PACKAGE__->register_method ({
 496     name => 'read_user_tfa_type',
 497     path => '{userid}/tfa',
 498     method => 'GET',
 499     protected => 1,
 500     description => "Get user TFA types (Personal and Realm).",
 501     permissions => {
 502         check => [ 'or',
 503             ['userid-param', 'self'],
 504             ['userid-group', ['User.Modify', 'Sys.Audit']],
 505         ],
 506     },
 507     parameters => {
 508         additionalProperties => 0,
 509         properties => {
 510             userid => get_standard_option('userid-completed'),
 511             multiple => {
 512                 type => 'boolean',
 513                 description => 'Request all entries as an array.',
 514                 optional => 1,
 515                 default => 0,
 516             },
 517         },
 518     },
 519     returns => {
 520         additionalProperties => 0,
 521         properties => {
 522             realm => {
 523                 type => 'string',
 524                 enum => [qw(oath yubico)],
 525                 description => "The type of TFA the users realm has set, if any.",
 526                 optional => 1,
 527             },
 528             user => {
 529                 type => 'string',
 530                 enum => [qw(oath u2f)],
 531                 description =>
 532                     "The type of TFA the user has set, if any."
 533                     . " Only set if 'multiple' was not passed.",
 534                 optional => 1,
 535             },
 536             types => {
 537                 type => 'array',
 538                 description =>
 539                     "Array of the user configured TFA types, if any."
 540                     . " Only available if 'multiple' was not passed.",
 541                 optional => 1,
 542                 items => {
 543                     type => 'string',
 544                     enum => [qw(totp u2f yubico webauthn recovedry)],
 545                     description => 'A TFA type.',
 546                 },
 547             },
 548         },
 549         type => "object"
 550     },
 551     code => sub {
 552         my ($param) = @_;
 553
 554         my ($username, undef, $realm) = PVE::AccessControl::verify_username($param->{userid});
 555
 556         my $domain_cfg = cfs_read_file('domains.cfg');
 557         my $realm_cfg = $domain_cfg->{ids}->{$realm};
 558         die "auth domain '$realm' does not exist\n" if !$realm_cfg;
 559
 560         my $res = {};
 561         my $realm_tfa = {};
 562         $realm_tfa = PVE::Auth::Plugin::parse_tfa_config($realm_cfg->{tfa}) if $realm_cfg->{tfa};
 563         $res->{realm} = $realm_tfa->{type} if $realm_tfa->{type};
 564
 565         my $tfa_cfg = cfs_read_file('priv/tfa.cfg');
 566         if ($param->{multiple}) {
 567             my $tfa = $tfa_cfg->get_user($username);
 568             my $user = [];
 569             foreach my $type (keys %$tfa) {
 570                 next if !scalar($tfa->{$type}->@*);
 571                 push @$user, $type;
 572             }
 573             $res->{user} = $user;
 574         } else {
 575             my $tfa = $tfa_cfg->{users}->{$username};
 576             $res->{user} = $tfa->{type} if $tfa->{type};
 577         }
 578         return $res;
 579     }});
 580
 581 __PACKAGE__->register_method ({
 582     name => 'unlock_tfa',
 583     path => '{userid}/unlock-tfa',
 584     method => 'PUT',
 585     protected => 1,
 586     description => "Unlock a user's TFA authentication.",
 587     permissions => {
 588         check => [ 'userid-group', ['User.Modify']],
 589     },
 590     parameters => {
 591         additionalProperties => 0,
 592         properties => {
 593             userid => get_standard_option('userid-completed'),
 594         },
 595     },
 596     returns => { type => 'boolean' },
 597     code => sub {
 598         my ($param) = @_;
 599
 600         my $userid = extract_param($param, "userid");
 601
 602         my $user_was_locked = PVE::AccessControl::lock_tfa_config(sub {
 603             my $tfa_cfg = cfs_read_file('priv/tfa.cfg');
 604             my $was_locked = $tfa_cfg->api_unlock_tfa($userid);
 605             cfs_write_file('priv/tfa.cfg', $tfa_cfg)
 606                 if $was_locked;
 607             return $was_locked;
 608         });
 609
 610         return $user_was_locked;
 611     }});
 612
 613 __PACKAGE__->register_method ({
 614     name => 'token_index',
 615     path => '{userid}/token',
 616     method => 'GET',
 617     description => "Get user API tokens.",
 618     permissions => {
 619         check => [
 620             'or',
 621             ['userid-param', 'self'],
 622             ['userid-group', ['User.Modify']],
 623         ],
 624     },
 625     parameters => {
 626         additionalProperties => 0,
 627         properties => {
 628             userid => get_standard_option('userid-completed'),
 629         },
 630     },
 631     returns => {
 632         type => "array",
 633         items => $token_info_extend->({
 634                     tokenid => get_standard_option('token-subid'),
 635         }),
 636         links => [ { rel => 'child', href => "{tokenid}" } ],
 637     },
 638     code => sub {
 639         my ($param) = @_;
 640
 641         my $userid = PVE::AccessControl::verify_username($param->{userid});
 642         my $usercfg = cfs_read_file("user.cfg");
 643
 644         my $user = PVE::AccessControl::check_user_exist($usercfg, $userid);
 645
 646         my $tokens = $user->{tokens} // {};
 647         return [ map { $tokens->{$_}->{tokenid} = $_; $tokens->{$_} } keys %$tokens];
 648     }});
 649
 650 __PACKAGE__->register_method ({
 651     name => 'read_token',
 652     path => '{userid}/token/{tokenid}',
 653     method => 'GET',
 654     description => "Get specific API token information.",
 655     permissions => {
 656         check => [
 657             'or',
 658             ['userid-param', 'self'],
 659             ['userid-group', ['User.Modify']],
 660         ],
 661     },
 662     parameters => {
 663         additionalProperties => 0,
 664         properties => {
 665             userid => get_standard_option('userid-completed'),
 666             tokenid => get_standard_option('token-subid'),
 667         },
 668     },
 669     returns => get_standard_option('token-info'),
 670     code => sub {
 671         my ($param) = @_;
 672
 673         my $userid = PVE::AccessControl::verify_username($param->{userid});
 674         my $tokenid = $param->{tokenid};
 675
 676         my $usercfg = cfs_read_file("user.cfg");
 677
 678         return PVE::AccessControl::check_token_exist($usercfg, $userid, $tokenid);
 679     }});
 680
 681 __PACKAGE__->register_method ({
 682     name => 'generate_token',
 683     path => '{userid}/token/{tokenid}',
 684     method => 'POST',
 685     description => "Generate a new API token for a specific user. NOTE: returns API token value, which needs to be stored as it cannot be retrieved afterwards!",
 686     protected => 1,
 687     permissions => {
 688         check => [
 689             'or',
 690             ['userid-param', 'self'],
 691             ['userid-group', ['User.Modify']],
 692         ],
 693     },
 694     parameters => {
 695         additionalProperties => 0,
 696         properties => {
 697             userid => get_standard_option('userid-completed'),
 698             tokenid => get_standard_option('token-subid'),
 699             expire => get_standard_option('token-expire'),
 700             privsep => get_standard_option('token-privsep'),
 701             comment => get_standard_option('token-comment'),
 702         },
 703     },
 704     returns => {
 705         additionalProperties => 0,
 706         type => "object",
 707         properties => {
 708             info => get_standard_option('token-info'),
 709             value => {
 710                 type => 'string',
 711                 description => 'API token value used for authentication.',
 712             },
 713             'full-tokenid' => {
 714                 type => 'string',
 715                 format_description => '<userid>!<tokenid>',
 716                 description => 'The full token id.',
 717             },
 718         },
 719     },
 720     code => sub {
 721         my ($param) = @_;
 722
 723         my $userid = PVE::AccessControl::verify_username(extract_param($param, 'userid'));
 724         my $tokenid = extract_param($param, 'tokenid');
 725
 726         my $usercfg = cfs_read_file("user.cfg");
 727
 728         my $token = PVE::AccessControl::check_token_exist($usercfg, $userid, $tokenid, 1);
 729         my ($full_tokenid, $value);
 730
 731         PVE::AccessControl::check_user_exist($usercfg, $userid);
 732         raise_param_exc({ 'tokenid' => 'Token already exists.' }) if defined($token);
 733
 734         my $generate_and_add_token = sub {
 735             $usercfg = cfs_read_file("user.cfg");
 736             PVE::AccessControl::check_user_exist($usercfg, $userid);
 737             die "Token already exists.\n" if defined(PVE::AccessControl::check_token_exist($usercfg, $userid, $tokenid, 1));
 738
 739             $full_tokenid = PVE::AccessControl::join_tokenid($userid, $tokenid);
 740             $value = PVE::TokenConfig::generate_token($full_tokenid);
 741
 742             $token = {};
 743             $token->{privsep} = defined($param->{privsep}) ? $param->{privsep} : 1;
 744             $token->{expire} = $param->{expire} if defined($param->{expire});
 745             $token->{comment} = $param->{comment} if $param->{comment};
 746
 747             $usercfg->{users}->{$userid}->{tokens}->{$tokenid} = $token;
 748             cfs_write_file("user.cfg", $usercfg);
 749         };
 750
 751         PVE::AccessControl::lock_user_config($generate_and_add_token, 'generating token failed');
 752
 753         return {
 754             info => $token,
 755             value => $value,
 756             'full-tokenid' => $full_tokenid,
 757         };
 758     }});
 759
 760
 761 __PACKAGE__->register_method ({
 762     name => 'update_token_info',
 763     path => '{userid}/token/{tokenid}',
 764     method => 'PUT',
 765     description => "Update API token for a specific user.",
 766     protected => 1,
 767     permissions => {
 768         check => [
 769             'or',
 770             ['userid-param', 'self'],
 771             ['userid-group', ['User.Modify']],
 772         ],
 773     },
 774     parameters => {
 775         additionalProperties => 0,
 776         properties => {
 777             userid => get_standard_option('userid-completed'),
 778             tokenid => get_standard_option('token-subid'),
 779             expire => get_standard_option('token-expire'),
 780             privsep => get_standard_option('token-privsep'),
 781             comment => get_standard_option('token-comment'),
 782         },
 783     },
 784     returns => get_standard_option('token-info', { description => "Updated token information." }),
 785     code => sub {
 786         my ($param) = @_;
 787
 788         my $userid = PVE::AccessControl::verify_username(extract_param($param, 'userid'));
 789         my $tokenid = extract_param($param, 'tokenid');
 790
 791         my $usercfg = cfs_read_file("user.cfg");
 792         my $token = PVE::AccessControl::check_token_exist($usercfg, $userid, $tokenid);
 793
 794         PVE::AccessControl::lock_user_config(sub {
 795             $usercfg = cfs_read_file("user.cfg");
 796             $token = PVE::AccessControl::check_token_exist($usercfg, $userid, $tokenid);
 797
 798             my $full_tokenid = PVE::AccessControl::join_tokenid($userid, $tokenid);
 799
 800             $token->{privsep} = $param->{privsep} if defined($param->{privsep});
 801             $token->{expire} = $param->{expire} if defined($param->{expire});
 802             $token->{comment} = $param->{comment} if $param->{comment};
 803
 804             $usercfg->{users}->{$userid}->{tokens}->{$tokenid} = $token;
 805             cfs_write_file("user.cfg", $usercfg);
 806         }, 'updating token info failed');
 807
 808         return $token;
 809     }});
 810
 811
 812 __PACKAGE__->register_method ({
 813     name => 'remove_token',
 814     path => '{userid}/token/{tokenid}',
 815     method => 'DELETE',
 816     description => "Remove API token for a specific user.",
 817     protected => 1,
 818     permissions => {
 819         check => [
 820             'or',
 821             ['userid-param', 'self'],
 822             ['userid-group', ['User.Modify']],
 823         ],
 824     },
 825     parameters => {
 826         additionalProperties => 0,
 827         properties => {
 828             userid => get_standard_option('userid-completed'),
 829             tokenid => get_standard_option('token-subid'),
 830         },
 831     },
 832     returns => { type => 'null' },
 833     code => sub {
 834         my ($param) = @_;
 835
 836         my $userid = PVE::AccessControl::verify_username(extract_param($param, 'userid'));
 837         my $tokenid = extract_param($param, 'tokenid');
 838
 839         my $usercfg = cfs_read_file("user.cfg");
 840         my $token = PVE::AccessControl::check_token_exist($usercfg, $userid, $tokenid);
 841
 842         PVE::AccessControl::lock_user_config(sub {
 843             $usercfg = cfs_read_file("user.cfg");
 844
 845             PVE::AccessControl::check_token_exist($usercfg, $userid, $tokenid);
 846
 847             my $full_tokenid = PVE::AccessControl::join_tokenid($userid, $tokenid);
 848             PVE::TokenConfig::delete_token($full_tokenid);
 849             delete $usercfg->{users}->{$userid}->{tokens}->{$tokenid};
 850
 851             cfs_write_file("user.cfg", $usercfg);
 852         }, 'deleting token failed');
 853
 854         return;
 855     }});
 856 1;