1 package PVE
::API2
::User
;
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);
12 use PVE
::AccessControl
;
13 use PVE
::Auth
::Plugin
;
18 use base
qw(PVE::RESTHandler);
20 register_standard_option
('user-enable', {
21 description
=> "Enable the account (default). You can set this to '0' to disable the account",
26 register_standard_option
('user-expire', {
27 description
=> "Account expiration date (seconds since epoch). '0' means no expiration date.",
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).",
41 register_standard_option
('group-list', {
42 type
=> 'string', format
=> 'pve-groupid-list',
44 completion
=> \
&PVE
::AccessControl
::complete_group
,
46 register_standard_option
('token-subid', {
48 pattern
=> $PVE::AccessControl
::token_subid_regex
,
49 description
=> 'User-specific token identifier.',
51 register_standard_option
('token-expire', {
52 description
=> "API token expiration date (seconds since epoch). '0' means no expiration date.",
56 default => 'same as user',
58 register_standard_option
('token-privsep', {
59 description
=> "Restrict API token privileges with separate ACLs (default), or give full privileges of corresponding user.",
64 register_standard_option
('token-comment', { type
=> 'string', optional
=> 1 });
65 register_standard_option
('token-info', {
68 expire
=> get_standard_option
('token-expire'),
69 privsep
=> get_standard_option
('token-privsep'),
70 comment
=> get_standard_option
('token-comment'),
74 my $token_info_extend = sub {
77 my $obj = get_standard_option
('token-info');
78 my $base_props = $obj->{properties
};
79 $obj->{properties
} = {};
81 foreach my $prop (keys %$base_props) {
82 $obj->{properties
}->{$prop} = $base_props->{$prop};
85 foreach my $add_prop (keys %$props) {
86 $obj->{properties
}->{$add_prop} = $props->{$add_prop};
92 my $extract_user_data = sub {
93 my ($data, $full) = @_;
97 foreach my $prop (qw(enable expire firstname lastname email comment keys)) {
98 $res->{$prop} = $data->{$prop} if defined($data->{$prop});
101 return $res if !$full;
103 $res->{groups
} = $data->{groups
} ?
[ keys %{$data->{groups
}} ] : [];
104 $res->{tokens
} = $data->{tokens
};
109 __PACKAGE__-
>register_method ({
113 description
=> "User index.",
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.",
119 additionalProperties
=> 0,
123 description
=> "Optional filter for enable property.",
128 description
=> "Include group and token information.",
139 userid
=> get_standard_option
('userid-completed'),
140 enable
=> get_standard_option
('user-enable'),
141 expire
=> get_standard_option
('user-expire'),
142 firstname
=> get_standard_option
('user-firstname'),
143 lastname
=> get_standard_option
('user-lastname'),
144 email
=> get_standard_option
('user-email'),
145 comment
=> get_standard_option
('user-comment'),
146 keys => get_standard_option
('user-keys'),
147 groups
=> get_standard_option
('group-list'),
151 items
=> $token_info_extend->({
152 tokenid
=> get_standard_option
('token-subid'),
156 type
=> 'string', format
=> 'pve-realm',
157 description
=> 'The type of the users realm',
158 optional
=> 1, # it should always be there, but we use conditional code below, so..
162 links
=> [ { rel
=> 'child', href
=> "{userid}" } ],
167 my $rpcenv = PVE
::RPCEnvironment
::get
();
168 my $usercfg = $rpcenv->{user_cfg
};
169 my $authuser = $rpcenv->get_user();
171 my $domainscfg = cfs_read_file
('domains.cfg');
172 my $domainids = $domainscfg->{ids
};
176 my $privs = [ 'User.Modify', 'Sys.Audit' ];
177 my $canUserMod = $rpcenv->check_any($authuser, "/access/groups", $privs, 1);
178 my $groups = $rpcenv->filter_groups($authuser, $privs, 1);
179 my $allowed_users = $rpcenv->group_member_join([keys %$groups]);
181 foreach my $user (sort keys %{$usercfg->{users
}}) {
182 if (!($canUserMod || $user eq $authuser)) {
183 next if !$allowed_users->{$user};
186 my $entry = $extract_user_data->($usercfg->{users
}->{$user}, $param->{full
});
188 if (defined($param->{enabled
})) {
189 next if $entry->{enable
} && !$param->{enabled
};
190 next if !$entry->{enable
} && $param->{enabled
};
193 $entry->{groups
} = join(',', @{$entry->{groups
}}) if $entry->{groups
};
195 if (defined(my $tokens = $entry->{tokens
})) {
197 map { { tokenid
=> $_, %{$tokens->{$_}} } } sort keys %$tokens
201 if ($user =~ /($PVE::Auth::Plugin::realm_regex)$/) {
203 $entry->{'realm-type'} = $domainids->{$realm}->{type
} if exists $domainids->{$realm};
206 $entry->{userid
} = $user;
214 __PACKAGE__-
>register_method ({
215 name
=> 'create_user',
220 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.",
223 [ 'userid-param', 'Realm.AllocateUser'],
224 [ 'userid-group', ['User.Modify'], groups_param
=> 'create'],
227 description
=> "Create new user.",
229 additionalProperties
=> 0,
231 userid
=> get_standard_option
('userid-completed'),
232 enable
=> get_standard_option
('user-enable'),
233 expire
=> get_standard_option
('user-expire'),
234 firstname
=> get_standard_option
('user-firstname'),
235 lastname
=> get_standard_option
('user-lastname'),
236 email
=> get_standard_option
('user-email'),
237 comment
=> get_standard_option
('user-comment'),
238 keys => get_standard_option
('user-keys'),
240 description
=> "Initial password.",
246 groups
=> get_standard_option
('group-list'),
249 returns
=> { type
=> 'null' },
253 PVE
::AccessControl
::lock_user_config
(sub {
254 my ($username, $ruid, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
256 my $usercfg = cfs_read_file
("user.cfg");
258 # ensure "user exists" check works for case insensitive realms
259 $username = PVE
::AccessControl
::lookup_username
($username, 1);
260 die "user '$username' already exists\n" if $usercfg->{users
}->{$username};
262 PVE
::AccessControl
::domain_set_password
($realm, $ruid, $param->{password
})
263 if defined($param->{password
});
265 my $enable = defined($param->{enable
}) ?
$param->{enable
} : 1;
266 $usercfg->{users
}->{$username} = { enable
=> $enable };
267 $usercfg->{users
}->{$username}->{expire
} = $param->{expire
} if $param->{expire
};
269 if ($param->{groups
}) {
270 foreach my $group (split_list
($param->{groups
})) {
271 if ($usercfg->{groups
}->{$group}) {
272 PVE
::AccessControl
::add_user_group
($username, $usercfg, $group);
274 die "no such group '$group'\n";
279 $usercfg->{users
}->{$username}->{firstname
} = $param->{firstname
} if $param->{firstname
};
280 $usercfg->{users
}->{$username}->{lastname
} = $param->{lastname
} if $param->{lastname
};
281 $usercfg->{users
}->{$username}->{email
} = $param->{email
} if $param->{email
};
282 $usercfg->{users
}->{$username}->{comment
} = $param->{comment
} if $param->{comment
};
283 $usercfg->{users
}->{$username}->{keys} = $param->{keys} if $param->{keys};
285 cfs_write_file
("user.cfg", $usercfg);
286 }, "create user failed");
291 __PACKAGE__-
>register_method ({
295 description
=> "Get user configuration.",
297 check
=> ['userid-group', ['User.Modify', 'Sys.Audit']],
300 additionalProperties
=> 0,
302 userid
=> get_standard_option
('userid-completed'),
306 additionalProperties
=> 0,
308 enable
=> get_standard_option
('user-enable'),
309 expire
=> get_standard_option
('user-expire'),
310 firstname
=> get_standard_option
('user-firstname'),
311 lastname
=> get_standard_option
('user-lastname'),
312 email
=> get_standard_option
('user-email'),
313 comment
=> get_standard_option
('user-comment'),
314 keys => get_standard_option
('user-keys'),
320 format
=> 'pve-groupid',
326 additionalProperties
=> get_standard_option
('token-info'),
334 my ($username, undef, $domain) = PVE
::AccessControl
::verify_username
($param->{userid
});
336 my $usercfg = cfs_read_file
("user.cfg");
338 my $data = PVE
::AccessControl
::check_user_exist
($usercfg, $username);
340 return &$extract_user_data($data, 1);
343 __PACKAGE__-
>register_method ({
344 name
=> 'update_user',
349 check
=> ['userid-group', ['User.Modify'], groups_param
=> 'update' ],
351 description
=> "Update user configuration.",
353 additionalProperties
=> 0,
355 userid
=> get_standard_option
('userid-completed'),
356 enable
=> get_standard_option
('user-enable'),
357 expire
=> get_standard_option
('user-expire'),
358 firstname
=> get_standard_option
('user-firstname'),
359 lastname
=> get_standard_option
('user-lastname'),
360 email
=> get_standard_option
('user-email'),
361 comment
=> get_standard_option
('user-comment'),
362 keys => get_standard_option
('user-keys'),
363 groups
=> get_standard_option
('group-list'),
367 requires
=> 'groups',
371 returns
=> { type
=> 'null' },
375 my ($username, $ruid, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
377 PVE
::AccessControl
::lock_user_config
(sub {
378 my $usercfg = cfs_read_file
("user.cfg");
380 PVE
::AccessControl
::check_user_exist
($usercfg, $username);
382 $usercfg->{users
}->{$username}->{enable
} = $param->{enable
} if defined($param->{enable
});
383 $usercfg->{users
}->{$username}->{expire
} = $param->{expire
} if defined($param->{expire
});
385 PVE
::AccessControl
::delete_user_group
($username, $usercfg)
386 if (!$param->{append
} && defined($param->{groups
}));
388 if ($param->{groups
}) {
389 foreach my $group (split_list
($param->{groups
})) {
390 if ($usercfg->{groups
}->{$group}) {
391 PVE
::AccessControl
::add_user_group
($username, $usercfg, $group);
393 die "no such group '$group'\n";
398 $usercfg->{users
}->{$username}->{firstname
} = $param->{firstname
} if defined($param->{firstname
});
399 $usercfg->{users
}->{$username}->{lastname
} = $param->{lastname
} if defined($param->{lastname
});
400 $usercfg->{users
}->{$username}->{email
} = $param->{email
} if defined($param->{email
});
401 $usercfg->{users
}->{$username}->{comment
} = $param->{comment
} if defined($param->{comment
});
402 $usercfg->{users
}->{$username}->{keys} = $param->{keys} if defined($param->{keys});
404 cfs_write_file
("user.cfg", $usercfg);
405 }, "update user failed");
410 __PACKAGE__-
>register_method ({
411 name
=> 'delete_user',
415 description
=> "Delete user.",
418 [ 'userid-param', 'Realm.AllocateUser'],
419 [ 'userid-group', ['User.Modify']],
423 additionalProperties
=> 0,
425 userid
=> get_standard_option
('userid-completed'),
428 returns
=> { type
=> 'null' },
432 my $rpcenv = PVE
::RPCEnvironment
::get
();
433 my $authuser = $rpcenv->get_user();
435 my ($userid, $ruid, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
437 PVE
::AccessControl
::lock_user_config
(sub {
438 my $usercfg = cfs_read_file
("user.cfg");
440 # NOTE: disable the user first (transaction like), so if (e.g.) we fail in the middle of
441 # TFA deletion the user will be still disabled and not just without TFA protection.
442 $usercfg->{users
}->{$userid}->{enable
} = 0;
443 cfs_write_file
("user.cfg", $usercfg);
445 my $domain_cfg = cfs_read_file
('domains.cfg');
446 if (my $cfg = $domain_cfg->{ids
}->{$realm}) {
447 my $plugin = PVE
::Auth
::Plugin-
>lookup($cfg->{type
});
448 $plugin->delete_user($cfg, $realm, $ruid);
451 # Remove user from cache before removing the TFA entry so realms with TFA-enforcement
452 # know that it's OK to drop any TFA entry in that case.
453 delete $usercfg->{users
}->{$userid};
455 my $partial_deletion = '';
457 PVE
::AccessControl
::user_remove_tfa
($userid);
458 $partial_deletion = ' - but deleted related TFA';
460 PVE
::AccessControl
::delete_user_group
($userid, $usercfg);
461 $partial_deletion .= ', Groups';
462 PVE
::AccessControl
::delete_user_acl
($userid, $usercfg);
463 $partial_deletion .= ', ACLs';
465 cfs_write_file
("user.cfg", $usercfg);
467 die "$@$partial_deletion\n" if $@;
468 }, "delete user failed");
473 __PACKAGE__-
>register_method ({
474 name
=> 'read_user_tfa_type',
475 path
=> '{userid}/tfa',
478 description
=> "Get user TFA types (Personal and Realm).",
481 ['userid-param', 'self'],
482 ['userid-group', ['User.Modify', 'Sys.Audit']],
486 additionalProperties
=> 0,
488 userid
=> get_standard_option
('userid-completed'),
491 description
=> 'Request all entries as an array.',
498 additionalProperties
=> 0,
502 enum
=> [qw(oath yubico)],
503 description
=> "The type of TFA the users realm has set, if any.",
508 enum
=> [qw(oath u2f)],
510 "The type of TFA the user has set, if any."
511 . " Only set if 'multiple' was not passed.",
517 "Array of the user configured TFA types, if any."
518 . " Only available if 'multiple' was not passed.",
522 enum
=> [qw(totp u2f yubico webauthn recovedry)],
523 description
=> 'A TFA type.',
532 my ($username, undef, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
534 my $domain_cfg = cfs_read_file
('domains.cfg');
535 my $realm_cfg = $domain_cfg->{ids
}->{$realm};
536 die "auth domain '$realm' does not exist\n" if !$realm_cfg;
540 $realm_tfa = PVE
::Auth
::Plugin
::parse_tfa_config
($realm_cfg->{tfa
}) if $realm_cfg->{tfa
};
541 $res->{realm
} = $realm_tfa->{type
} if $realm_tfa->{type
};
543 my $tfa_cfg = cfs_read_file
('priv/tfa.cfg');
544 if ($param->{multiple
}) {
545 my $tfa = $tfa_cfg->get_user($username);
547 foreach my $type (keys %$tfa) {
548 next if !scalar($tfa->{$type}->@*);
551 $res->{user
} = $user;
553 my $tfa = $tfa_cfg->{users
}->{$username};
554 $res->{user
} = $tfa->{type
} if $tfa->{type
};
559 __PACKAGE__-
>register_method ({
560 name
=> 'unlock_tfa',
561 path
=> '{userid}/unlock-tfa',
564 description
=> "Unlock a user's TFA authentication.",
566 check
=> [ 'userid-group', ['User.Modify']],
569 additionalProperties
=> 0,
571 userid
=> get_standard_option
('userid-completed'),
574 returns
=> { type
=> 'boolean' },
578 my $userid = extract_param
($param, "userid");
580 my $user_was_locked = PVE
::AccessControl
::lock_tfa_config
(sub {
581 my $tfa_cfg = cfs_read_file
('priv/tfa.cfg');
582 my $was_locked = $tfa_cfg->api_unlock_tfa($userid);
583 cfs_write_file
('priv/tfa.cfg', $tfa_cfg)
588 return $user_was_locked;
591 __PACKAGE__-
>register_method ({
592 name
=> 'token_index',
593 path
=> '{userid}/token',
595 description
=> "Get user API tokens.",
599 ['userid-param', 'self'],
600 ['userid-group', ['User.Modify']],
604 additionalProperties
=> 0,
606 userid
=> get_standard_option
('userid-completed'),
611 items
=> $token_info_extend->({
612 tokenid
=> get_standard_option
('token-subid'),
614 links
=> [ { rel
=> 'child', href
=> "{tokenid}" } ],
619 my $userid = PVE
::AccessControl
::verify_username
($param->{userid
});
620 my $usercfg = cfs_read_file
("user.cfg");
622 my $user = PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
624 my $tokens = $user->{tokens
} // {};
625 return [ map { $tokens->{$_}->{tokenid
} = $_; $tokens->{$_} } keys %$tokens];
628 __PACKAGE__-
>register_method ({
629 name
=> 'read_token',
630 path
=> '{userid}/token/{tokenid}',
632 description
=> "Get specific API token information.",
636 ['userid-param', 'self'],
637 ['userid-group', ['User.Modify']],
641 additionalProperties
=> 0,
643 userid
=> get_standard_option
('userid-completed'),
644 tokenid
=> get_standard_option
('token-subid'),
647 returns
=> get_standard_option
('token-info'),
651 my $userid = PVE
::AccessControl
::verify_username
($param->{userid
});
652 my $tokenid = $param->{tokenid
};
654 my $usercfg = cfs_read_file
("user.cfg");
656 return PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
659 __PACKAGE__-
>register_method ({
660 name
=> 'generate_token',
661 path
=> '{userid}/token/{tokenid}',
663 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!",
668 ['userid-param', 'self'],
669 ['userid-group', ['User.Modify']],
673 additionalProperties
=> 0,
675 userid
=> get_standard_option
('userid-completed'),
676 tokenid
=> get_standard_option
('token-subid'),
677 expire
=> get_standard_option
('token-expire'),
678 privsep
=> get_standard_option
('token-privsep'),
679 comment
=> get_standard_option
('token-comment'),
683 additionalProperties
=> 0,
686 info
=> get_standard_option
('token-info'),
689 description
=> 'API token value used for authentication.',
693 format_description
=> '<userid>!<tokenid>',
694 description
=> 'The full token id.',
701 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
702 my $tokenid = extract_param
($param, 'tokenid');
704 my $usercfg = cfs_read_file
("user.cfg");
706 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid, 1);
707 my ($full_tokenid, $value);
709 PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
710 raise_param_exc
({ 'tokenid' => 'Token already exists.' }) if defined($token);
712 my $generate_and_add_token = sub {
713 $usercfg = cfs_read_file
("user.cfg");
714 PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
715 die "Token already exists.\n" if defined(PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid, 1));
717 $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
718 $value = PVE
::TokenConfig
::generate_token
($full_tokenid);
721 $token->{privsep
} = defined($param->{privsep
}) ?
$param->{privsep
} : 1;
722 $token->{expire
} = $param->{expire
} if defined($param->{expire
});
723 $token->{comment
} = $param->{comment
} if $param->{comment
};
725 $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid} = $token;
726 cfs_write_file
("user.cfg", $usercfg);
729 PVE
::AccessControl
::lock_user_config
($generate_and_add_token, 'generating token failed');
734 'full-tokenid' => $full_tokenid,
739 __PACKAGE__-
>register_method ({
740 name
=> 'update_token_info',
741 path
=> '{userid}/token/{tokenid}',
743 description
=> "Update API token for a specific user.",
748 ['userid-param', 'self'],
749 ['userid-group', ['User.Modify']],
753 additionalProperties
=> 0,
755 userid
=> get_standard_option
('userid-completed'),
756 tokenid
=> get_standard_option
('token-subid'),
757 expire
=> get_standard_option
('token-expire'),
758 privsep
=> get_standard_option
('token-privsep'),
759 comment
=> get_standard_option
('token-comment'),
762 returns
=> get_standard_option
('token-info', { description
=> "Updated token information." }),
766 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
767 my $tokenid = extract_param
($param, 'tokenid');
769 my $usercfg = cfs_read_file
("user.cfg");
770 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
772 PVE
::AccessControl
::lock_user_config
(sub {
773 $usercfg = cfs_read_file
("user.cfg");
774 $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
776 my $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
778 $token->{privsep
} = $param->{privsep
} if defined($param->{privsep
});
779 $token->{expire
} = $param->{expire
} if defined($param->{expire
});
780 $token->{comment
} = $param->{comment
} if $param->{comment
};
782 $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid} = $token;
783 cfs_write_file
("user.cfg", $usercfg);
784 }, 'updating token info failed');
790 __PACKAGE__-
>register_method ({
791 name
=> 'remove_token',
792 path
=> '{userid}/token/{tokenid}',
794 description
=> "Remove API token for a specific user.",
799 ['userid-param', 'self'],
800 ['userid-group', ['User.Modify']],
804 additionalProperties
=> 0,
806 userid
=> get_standard_option
('userid-completed'),
807 tokenid
=> get_standard_option
('token-subid'),
810 returns
=> { type
=> 'null' },
814 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
815 my $tokenid = extract_param
($param, 'tokenid');
817 my $usercfg = cfs_read_file
("user.cfg");
818 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
820 PVE
::AccessControl
::lock_user_config
(sub {
821 $usercfg = cfs_read_file
("user.cfg");
823 PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
825 my $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
826 PVE
::TokenConfig
::delete_token
($full_tokenid);
827 delete $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid};
829 cfs_write_file
("user.cfg", $usercfg);
830 }, 'deleting token failed');