1 package PVE
::API2
::User
;
5 use PVE
::Exception
qw(raise raise_perm_exc raise_param_exc);
6 use PVE
::Cluster qw
(cfs_read_file cfs_write_file
);
7 use PVE
::Tools
qw(split_list extract_param);
8 use PVE
::AccessControl
;
9 use PVE
::JSONSchema
qw(get_standard_option register_standard_option);
16 use base
qw(PVE::RESTHandler);
18 register_standard_option
('user-enable', {
19 description
=> "Enable the account (default). You can set this to '0' to disable the account",
24 register_standard_option
('user-expire', {
25 description
=> "Account expiration date (seconds since epoch). '0' means no expiration date.",
30 register_standard_option
('user-firstname', { type
=> 'string', optional
=> 1 });
31 register_standard_option
('user-lastname', { type
=> 'string', optional
=> 1 });
32 register_standard_option
('user-email', { type
=> 'string', optional
=> 1, format
=> 'email-opt' });
33 register_standard_option
('user-comment', { type
=> 'string', optional
=> 1 });
34 register_standard_option
('user-keys', {
35 description
=> "Keys for two factor auth (yubico).",
39 register_standard_option
('group-list', {
40 type
=> 'string', format
=> 'pve-groupid-list',
42 completion
=> \
&PVE
::AccessControl
::complete_group
,
44 register_standard_option
('token-subid', {
46 pattern
=> $PVE::AccessControl
::token_subid_regex
,
47 description
=> 'User-specific token identifier.',
49 register_standard_option
('token-expire', {
50 description
=> "API token expiration date (seconds since epoch). '0' means no expiration date.",
54 default => 'same as user',
56 register_standard_option
('token-privsep', {
57 description
=> "Restrict API token privileges with separate ACLs (default), or give full privileges of corresponding user.",
62 register_standard_option
('token-comment', { type
=> 'string', optional
=> 1 });
63 register_standard_option
('token-info', {
66 expire
=> get_standard_option
('token-expire'),
67 privsep
=> get_standard_option
('token-privsep'),
68 comment
=> get_standard_option
('token-comment'),
72 my $token_info_extend = sub {
75 my $obj = get_standard_option
('token-info');
76 my $base_props = $obj->{properties
};
77 $obj->{properties
} = {};
79 foreach my $prop (keys %$base_props) {
80 $obj->{properties
}->{$prop} = $base_props->{$prop};
83 foreach my $add_prop (keys %$props) {
84 $obj->{properties
}->{$add_prop} = $props->{$add_prop};
90 my $extract_user_data = sub {
91 my ($data, $full) = @_;
95 foreach my $prop (qw(enable expire firstname lastname email comment keys)) {
96 $res->{$prop} = $data->{$prop} if defined($data->{$prop});
99 return $res if !$full;
101 $res->{groups
} = $data->{groups
} ?
[ keys %{$data->{groups
}} ] : [];
102 $res->{tokens
} = $data->{tokens
};
107 __PACKAGE__-
>register_method ({
111 description
=> "User index.",
113 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.",
117 additionalProperties
=> 0,
121 description
=> "Optional filter for enable property.",
126 description
=> "Include group and token information.",
137 userid
=> get_standard_option
('userid-completed'),
138 enable
=> get_standard_option
('user-enable'),
139 expire
=> get_standard_option
('user-expire'),
140 firstname
=> get_standard_option
('user-firstname'),
141 lastname
=> get_standard_option
('user-lastname'),
142 email
=> get_standard_option
('user-email'),
143 comment
=> get_standard_option
('user-comment'),
144 keys => get_standard_option
('user-keys'),
145 groups
=> get_standard_option
('group-list'),
149 items
=> $token_info_extend->({
150 tokenid
=> get_standard_option
('token-subid'),
155 links
=> [ { rel
=> 'child', href
=> "{userid}" } ],
160 my $rpcenv = PVE
::RPCEnvironment
::get
();
161 my $usercfg = $rpcenv->{user_cfg
};
162 my $authuser = $rpcenv->get_user();
166 my $privs = [ 'User.Modify', 'Sys.Audit' ];
167 my $canUserMod = $rpcenv->check_any($authuser, "/access/groups", $privs, 1);
168 my $groups = $rpcenv->filter_groups($authuser, $privs, 1);
169 my $allowed_users = $rpcenv->group_member_join([keys %$groups]);
171 foreach my $user (keys %{$usercfg->{users
}}) {
172 if (!($canUserMod || $user eq $authuser)) {
173 next if !$allowed_users->{$user};
176 my $entry = &$extract_user_data($usercfg->{users
}->{$user}, $param->{full
});
178 if (defined($param->{enabled
})) {
179 next if $entry->{enable
} && !$param->{enabled
};
180 next if !$entry->{enable
} && $param->{enabled
};
183 $entry->{groups
} = join(',', @{$entry->{groups
}}) if $entry->{groups
};
184 $entry->{tokens
} = [ map { { tokenid
=> $_, %{$entry->{tokens
}->{$_}} } } sort keys %{$entry->{tokens
}} ]
185 if defined($entry->{tokens
});
187 $entry->{userid
} = $user;
194 __PACKAGE__-
>register_method ({
195 name
=> 'create_user',
200 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.",
202 [ 'userid-param', 'Realm.AllocateUser'],
203 [ 'userid-group', ['User.Modify'], groups_param
=> 1],
206 description
=> "Create new user.",
208 additionalProperties
=> 0,
210 userid
=> get_standard_option
('userid-completed'),
211 enable
=> get_standard_option
('user-enable'),
212 expire
=> get_standard_option
('user-expire'),
213 firstname
=> get_standard_option
('user-firstname'),
214 lastname
=> get_standard_option
('user-lastname'),
215 email
=> get_standard_option
('user-email'),
216 comment
=> get_standard_option
('user-comment'),
217 keys => get_standard_option
('user-keys'),
219 description
=> "Initial password.",
225 groups
=> get_standard_option
('group-list'),
228 returns
=> { type
=> 'null' },
232 PVE
::AccessControl
::lock_user_config
(sub {
233 my ($username, $ruid, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
235 my $usercfg = cfs_read_file
("user.cfg");
237 # ensure "user exists" check works for case insensitive realms
238 $username = PVE
::AccessControl
::lookup_username
($username, 1);
239 die "user '$username' already exists\n" if $usercfg->{users
}->{$username};
241 PVE
::AccessControl
::domain_set_password
($realm, $ruid, $param->{password
})
242 if defined($param->{password
});
244 my $enable = defined($param->{enable
}) ?
$param->{enable
} : 1;
245 $usercfg->{users
}->{$username} = { enable
=> $enable };
246 $usercfg->{users
}->{$username}->{expire
} = $param->{expire
} if $param->{expire
};
248 if ($param->{groups
}) {
249 foreach my $group (split_list
($param->{groups
})) {
250 if ($usercfg->{groups
}->{$group}) {
251 PVE
::AccessControl
::add_user_group
($username, $usercfg, $group);
253 die "no such group '$group'\n";
258 $usercfg->{users
}->{$username}->{firstname
} = $param->{firstname
} if $param->{firstname
};
259 $usercfg->{users
}->{$username}->{lastname
} = $param->{lastname
} if $param->{lastname
};
260 $usercfg->{users
}->{$username}->{email
} = $param->{email
} if $param->{email
};
261 $usercfg->{users
}->{$username}->{comment
} = $param->{comment
} if $param->{comment
};
262 $usercfg->{users
}->{$username}->{keys} = $param->{keys} if $param->{keys};
264 cfs_write_file
("user.cfg", $usercfg);
265 }, "create user failed");
270 __PACKAGE__-
>register_method ({
274 description
=> "Get user configuration.",
276 check
=> ['userid-group', ['User.Modify', 'Sys.Audit']],
279 additionalProperties
=> 0,
281 userid
=> get_standard_option
('userid-completed'),
285 additionalProperties
=> 0,
287 enable
=> get_standard_option
('user-enable'),
288 expire
=> get_standard_option
('user-expire'),
289 firstname
=> get_standard_option
('user-firstname'),
290 lastname
=> get_standard_option
('user-lastname'),
291 email
=> get_standard_option
('user-email'),
292 comment
=> get_standard_option
('user-comment'),
293 keys => get_standard_option
('user-keys'),
299 format
=> 'pve-groupid',
312 my ($username, undef, $domain) =
313 PVE
::AccessControl
::verify_username
($param->{userid
});
315 my $usercfg = cfs_read_file
("user.cfg");
317 my $data = PVE
::AccessControl
::check_user_exist
($usercfg, $username);
319 return &$extract_user_data($data, 1);
322 __PACKAGE__-
>register_method ({
323 name
=> 'update_user',
328 check
=> ['userid-group', ['User.Modify'], groups_param
=> 1 ],
330 description
=> "Update user configuration.",
332 additionalProperties
=> 0,
334 userid
=> get_standard_option
('userid-completed'),
335 enable
=> get_standard_option
('user-enable'),
336 expire
=> get_standard_option
('user-expire'),
337 firstname
=> get_standard_option
('user-firstname'),
338 lastname
=> get_standard_option
('user-lastname'),
339 email
=> get_standard_option
('user-email'),
340 comment
=> get_standard_option
('user-comment'),
341 keys => get_standard_option
('user-keys'),
342 groups
=> get_standard_option
('group-list'),
346 requires
=> 'groups',
350 returns
=> { type
=> 'null' },
354 my ($username, $ruid, $realm) =
355 PVE
::AccessControl
::verify_username
($param->{userid
});
357 PVE
::AccessControl
::lock_user_config
(
360 my $usercfg = cfs_read_file
("user.cfg");
362 PVE
::AccessControl
::check_user_exist
($usercfg, $username);
364 $usercfg->{users
}->{$username}->{enable
} = $param->{enable
} if defined($param->{enable
});
366 $usercfg->{users
}->{$username}->{expire
} = $param->{expire
} if defined($param->{expire
});
368 PVE
::AccessControl
::delete_user_group
($username, $usercfg)
369 if (!$param->{append
} && defined($param->{groups
}));
371 if ($param->{groups
}) {
372 foreach my $group (split_list
($param->{groups
})) {
373 if ($usercfg->{groups
}->{$group}) {
374 PVE
::AccessControl
::add_user_group
($username, $usercfg, $group);
376 die "no such group '$group'\n";
381 $usercfg->{users
}->{$username}->{firstname
} = $param->{firstname
} if defined($param->{firstname
});
382 $usercfg->{users
}->{$username}->{lastname
} = $param->{lastname
} if defined($param->{lastname
});
383 $usercfg->{users
}->{$username}->{email
} = $param->{email
} if defined($param->{email
});
384 $usercfg->{users
}->{$username}->{comment
} = $param->{comment
} if defined($param->{comment
});
385 $usercfg->{users
}->{$username}->{keys} = $param->{keys} if defined($param->{keys});
387 cfs_write_file
("user.cfg", $usercfg);
388 }, "update user failed");
393 __PACKAGE__-
>register_method ({
394 name
=> 'delete_user',
398 description
=> "Delete user.",
401 [ 'userid-param', 'Realm.AllocateUser'],
402 [ 'userid-group', ['User.Modify']],
406 additionalProperties
=> 0,
408 userid
=> get_standard_option
('userid-completed'),
411 returns
=> { type
=> 'null' },
415 my $rpcenv = PVE
::RPCEnvironment
::get
();
416 my $authuser = $rpcenv->get_user();
418 my ($userid, $ruid, $realm) =
419 PVE
::AccessControl
::verify_username
($param->{userid
});
421 PVE
::AccessControl
::lock_user_config
(
424 my $usercfg = cfs_read_file
("user.cfg");
426 my $domain_cfg = cfs_read_file
('domains.cfg');
427 if (my $cfg = $domain_cfg->{ids
}->{$realm}) {
428 my $plugin = PVE
::Auth
::Plugin-
>lookup($cfg->{type
});
429 $plugin->delete_user($cfg, $realm, $ruid);
432 # Remove TFA data before removing the user entry as the user entry tells us whether
433 # we need ot update priv/tfa.cfg.
434 PVE
::AccessControl
::user_set_tfa
($userid, $realm, undef, undef, $usercfg, $domain_cfg);
436 delete $usercfg->{users
}->{$userid};
438 PVE
::AccessControl
::delete_user_group
($userid, $usercfg);
439 PVE
::AccessControl
::delete_user_acl
($userid, $usercfg);
440 cfs_write_file
("user.cfg", $usercfg);
441 }, "delete user failed");
446 __PACKAGE__-
>register_method ({
447 name
=> 'read_user_tfa_type',
448 path
=> '{userid}/tfa',
451 description
=> "Get user TFA types (Personal and Realm).",
454 ['userid-param', 'self'],
455 ['userid-group', ['User.Modify', 'Sys.Audit']],
459 additionalProperties
=> 0,
461 userid
=> get_standard_option
('userid-completed'),
465 additionalProperties
=> 0,
469 enum
=> [qw(oath yubico)],
470 description
=> "The type of TFA the users realm has set, if any.",
475 enum
=> [qw(oath u2f)],
476 description
=> "The type of TFA the user has set, if any.",
485 my ($username, undef, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
488 my $domain_cfg = cfs_read_file
('domains.cfg');
489 my $realm_cfg = $domain_cfg->{ids
}->{$realm};
490 die "auth domain '$realm' does not exist\n" if !$realm_cfg;
493 $realm_tfa = PVE
::Auth
::Plugin
::parse_tfa_config
($realm_cfg->{tfa
})
494 if $realm_cfg->{tfa
};
496 my $tfa_cfg = cfs_read_file
('priv/tfa.cfg');
497 my $tfa = $tfa_cfg->{users
}->{$username};
500 $res->{realm
} = $realm_tfa->{type
} if $realm_tfa->{type
};
501 $res->{user
} = $tfa->{type
} if $tfa->{type
};
505 __PACKAGE__-
>register_method ({
506 name
=> 'token_index',
507 path
=> '{userid}/token',
509 description
=> "Get user API tokens.",
512 ['userid-param', 'self'],
513 ['perm', '/access/users/{userid}', ['User.Modify']],
517 additionalProperties
=> 0,
519 userid
=> get_standard_option
('userid-completed'),
524 items
=> $token_info_extend->({
525 tokenid
=> get_standard_option
('token-subid'),
527 links
=> [ { rel
=> 'child', href
=> "{tokenid}" } ],
532 my $userid = PVE
::AccessControl
::verify_username
($param->{userid
});
533 my $usercfg = cfs_read_file
("user.cfg");
535 my $user = PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
537 my $tokens = $user->{tokens
} // {};
538 return [ map { $tokens->{$_}->{tokenid
} = $_; $tokens->{$_} } keys %$tokens];
541 __PACKAGE__-
>register_method ({
542 name
=> 'read_token',
543 path
=> '{userid}/token/{tokenid}',
545 description
=> "Get specific API token information.",
548 ['userid-param', 'self'],
549 ['perm', '/access/users/{userid}', ['User.Modify']],
553 additionalProperties
=> 0,
555 userid
=> get_standard_option
('userid-completed'),
556 tokenid
=> get_standard_option
('token-subid'),
559 returns
=> get_standard_option
('token-info'),
563 my $userid = PVE
::AccessControl
::verify_username
($param->{userid
});
564 my $tokenid = $param->{tokenid
};
566 my $usercfg = cfs_read_file
("user.cfg");
568 return PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
571 __PACKAGE__-
>register_method ({
572 name
=> 'generate_token',
573 path
=> '{userid}/token/{tokenid}',
575 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!",
579 ['userid-param', 'self'],
580 ['perm', '/access/users/{userid}', ['User.Modify']],
584 additionalProperties
=> 0,
586 userid
=> get_standard_option
('userid-completed'),
587 tokenid
=> get_standard_option
('token-subid'),
588 expire
=> get_standard_option
('token-expire'),
589 privsep
=> get_standard_option
('token-privsep'),
590 comment
=> get_standard_option
('token-comment'),
594 additionalProperties
=> 0,
597 info
=> get_standard_option
('token-info'),
600 description
=> 'API token value used for authentication.',
604 format_description
=> '<userid>!<tokenid>',
605 description
=> 'The full token id.',
612 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
613 my $tokenid = extract_param
($param, 'tokenid');
615 my $usercfg = cfs_read_file
("user.cfg");
617 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid, 1);
618 my ($full_tokenid, $value);
620 PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
621 raise_param_exc
({ 'tokenid' => 'Token already exists.' }) if defined($token);
623 my $generate_and_add_token = sub {
624 $usercfg = cfs_read_file
("user.cfg");
625 PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
626 die "Token already exists.\n" if defined(PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid, 1));
628 $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
629 $value = PVE
::TokenConfig
::generate_token
($full_tokenid);
632 $token->{privsep
} = defined($param->{privsep
}) ?
$param->{privsep
} : 1;
633 $token->{expire
} = $param->{expire
} if defined($param->{expire
});
634 $token->{comment
} = $param->{comment
} if $param->{comment
};
636 $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid} = $token;
637 cfs_write_file
("user.cfg", $usercfg);
640 PVE
::AccessControl
::lock_user_config
($generate_and_add_token, 'generating token failed');
645 'full-tokenid' => $full_tokenid,
650 __PACKAGE__-
>register_method ({
651 name
=> 'update_token_info',
652 path
=> '{userid}/token/{tokenid}',
654 description
=> "Update API token for a specific user.",
658 ['userid-param', 'self'],
659 ['perm', '/access/users/{userid}', ['User.Modify']],
663 additionalProperties
=> 0,
665 userid
=> get_standard_option
('userid-completed'),
666 tokenid
=> get_standard_option
('token-subid'),
667 expire
=> get_standard_option
('token-expire'),
668 privsep
=> get_standard_option
('token-privsep'),
669 comment
=> get_standard_option
('token-comment'),
672 returns
=> get_standard_option
('token-info', { description
=> "Updated token information." }),
676 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
677 my $tokenid = extract_param
($param, 'tokenid');
679 my $usercfg = cfs_read_file
("user.cfg");
680 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
682 my $update_token = sub {
683 $usercfg = cfs_read_file
("user.cfg");
684 $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
686 my $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
688 $token->{privsep
} = $param->{privsep
} if defined($param->{privsep
});
689 $token->{expire
} = $param->{expire
} if defined($param->{expire
});
690 $token->{comment
} = $param->{comment
} if $param->{comment
};
692 $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid} = $token;
693 cfs_write_file
("user.cfg", $usercfg);
696 PVE
::AccessControl
::lock_user_config
($update_token, 'updating token info failed');
702 __PACKAGE__-
>register_method ({
703 name
=> 'remove_token',
704 path
=> '{userid}/token/{tokenid}',
706 description
=> "Remove API token for a specific user.",
710 ['userid-param', 'self'],
711 ['perm', '/access/users/{userid}', ['User.Modify']],
715 additionalProperties
=> 0,
717 userid
=> get_standard_option
('userid-completed'),
718 tokenid
=> get_standard_option
('token-subid'),
721 returns
=> { type
=> 'null' },
725 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
726 my $tokenid = extract_param
($param, 'tokenid');
728 my $usercfg = cfs_read_file
("user.cfg");
729 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
731 my $update_token = sub {
732 $usercfg = cfs_read_file
("user.cfg");
734 PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
736 my $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
737 PVE
::TokenConfig
::delete_token
($full_tokenid);
738 delete $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid};
740 cfs_write_file
("user.cfg", $usercfg);
743 PVE
::AccessControl
::lock_user_config
($update_token, 'deleting token failed');