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.",
55 register_standard_option
('token-privsep', {
56 description
=> "Restrict API token privileges with separate ACLs (default), or give full privileges of corresponding user.",
61 register_standard_option
('token-comment', { type
=> 'string', optional
=> 1 });
62 register_standard_option
('token-info', {
65 expire
=> get_standard_option
('token-expire'),
66 privsep
=> get_standard_option
('token-privsep'),
67 comment
=> get_standard_option
('token-comment'),
71 my $token_info_extend = sub {
74 my $obj = get_standard_option
('token-info');
75 my $base_props = $obj->{properties
};
76 $obj->{properties
} = {};
78 foreach my $prop (keys %$base_props) {
79 $obj->{properties
}->{$prop} = $base_props->{$prop};
82 foreach my $add_prop (keys %$props) {
83 $obj->{properties
}->{$add_prop} = $props->{$add_prop};
89 my $extract_user_data = sub {
90 my ($data, $full) = @_;
94 foreach my $prop (qw(enable expire firstname lastname email comment keys)) {
95 $res->{$prop} = $data->{$prop} if defined($data->{$prop});
98 return $res if !$full;
100 $res->{groups
} = $data->{groups
} ?
[ keys %{$data->{groups
}} ] : [];
101 $res->{tokens
} = $data->{tokens
};
106 __PACKAGE__-
>register_method ({
110 description
=> "User index.",
112 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 additionalProperties
=> 0,
120 description
=> "Optional filter for enable property.",
130 userid
=> get_standard_option
('userid-completed'),
131 enable
=> get_standard_option
('user-enable'),
132 expire
=> get_standard_option
('user-expire'),
133 firstname
=> get_standard_option
('user-firstname'),
134 lastname
=> get_standard_option
('user-lastname'),
135 email
=> get_standard_option
('user-email'),
136 comment
=> get_standard_option
('user-comment'),
137 keys => get_standard_option
('user-keys'),
140 links
=> [ { rel
=> 'child', href
=> "{userid}" } ],
145 my $rpcenv = PVE
::RPCEnvironment
::get
();
146 my $usercfg = $rpcenv->{user_cfg
};
147 my $authuser = $rpcenv->get_user();
151 my $privs = [ 'User.Modify', 'Sys.Audit' ];
152 my $canUserMod = $rpcenv->check_any($authuser, "/access/groups", $privs, 1);
153 my $groups = $rpcenv->filter_groups($authuser, $privs, 1);
154 my $allowed_users = $rpcenv->group_member_join([keys %$groups]);
156 foreach my $user (keys %{$usercfg->{users
}}) {
158 if (!($canUserMod || $user eq $authuser)) {
159 next if !$allowed_users->{$user};
162 my $entry = &$extract_user_data($usercfg->{users
}->{$user});
164 if (defined($param->{enabled
})) {
165 next if $entry->{enable
} && !$param->{enabled
};
166 next if !$entry->{enable
} && $param->{enabled
};
169 $entry->{userid
} = $user;
176 __PACKAGE__-
>register_method ({
177 name
=> 'create_user',
182 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.",
184 [ 'userid-param', 'Realm.AllocateUser'],
185 [ 'userid-group', ['User.Modify'], groups_param
=> 1],
188 description
=> "Create new user.",
190 additionalProperties
=> 0,
192 userid
=> get_standard_option
('userid-completed'),
193 enable
=> get_standard_option
('user-enable'),
194 expire
=> get_standard_option
('user-expire'),
195 firstname
=> get_standard_option
('user-firstname'),
196 lastname
=> get_standard_option
('user-lastname'),
197 email
=> get_standard_option
('user-email'),
198 comment
=> get_standard_option
('user-comment'),
199 keys => get_standard_option
('user-keys'),
201 description
=> "Initial password.",
207 groups
=> get_standard_option
('group-list'),
210 returns
=> { type
=> 'null' },
214 PVE
::AccessControl
::lock_user_config
(
217 my ($username, $ruid, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
219 my $usercfg = cfs_read_file
("user.cfg");
221 die "user '$username' already exists\n"
222 if $usercfg->{users
}->{$username};
224 PVE
::AccessControl
::domain_set_password
($realm, $ruid, $param->{password
})
225 if defined($param->{password
});
227 my $enable = defined($param->{enable
}) ?
$param->{enable
} : 1;
228 $usercfg->{users
}->{$username} = { enable
=> $enable };
229 $usercfg->{users
}->{$username}->{expire
} = $param->{expire
} if $param->{expire
};
231 if ($param->{groups
}) {
232 foreach my $group (split_list
($param->{groups
})) {
233 if ($usercfg->{groups
}->{$group}) {
234 PVE
::AccessControl
::add_user_group
($username, $usercfg, $group);
236 die "no such group '$group'\n";
241 $usercfg->{users
}->{$username}->{firstname
} = $param->{firstname
} if $param->{firstname
};
242 $usercfg->{users
}->{$username}->{lastname
} = $param->{lastname
} if $param->{lastname
};
243 $usercfg->{users
}->{$username}->{email
} = $param->{email
} if $param->{email
};
244 $usercfg->{users
}->{$username}->{comment
} = $param->{comment
} if $param->{comment
};
245 $usercfg->{users
}->{$username}->{keys} = $param->{keys} if $param->{keys};
247 cfs_write_file
("user.cfg", $usercfg);
248 }, "create user failed");
253 __PACKAGE__-
>register_method ({
257 description
=> "Get user configuration.",
259 check
=> ['userid-group', ['User.Modify', 'Sys.Audit']],
262 additionalProperties
=> 0,
264 userid
=> get_standard_option
('userid-completed'),
268 additionalProperties
=> 0,
270 enable
=> get_standard_option
('user-enable'),
271 expire
=> get_standard_option
('user-expire'),
272 firstname
=> get_standard_option
('user-firstname'),
273 lastname
=> get_standard_option
('user-lastname'),
274 email
=> get_standard_option
('user-email'),
275 comment
=> get_standard_option
('user-comment'),
276 keys => get_standard_option
('user-keys'),
281 format
=> 'pve-groupid',
293 my ($username, undef, $domain) =
294 PVE
::AccessControl
::verify_username
($param->{userid
});
296 my $usercfg = cfs_read_file
("user.cfg");
298 my $data = PVE
::AccessControl
::check_user_exist
($usercfg, $username);
300 return &$extract_user_data($data, 1);
303 __PACKAGE__-
>register_method ({
304 name
=> 'update_user',
309 check
=> ['userid-group', ['User.Modify'], groups_param
=> 1 ],
311 description
=> "Update user configuration.",
313 additionalProperties
=> 0,
315 userid
=> get_standard_option
('userid-completed'),
316 enable
=> get_standard_option
('user-enable'),
317 expire
=> get_standard_option
('user-expire'),
318 firstname
=> get_standard_option
('user-firstname'),
319 lastname
=> get_standard_option
('user-lastname'),
320 email
=> get_standard_option
('user-email'),
321 comment
=> get_standard_option
('user-comment'),
322 keys => get_standard_option
('user-keys'),
323 groups
=> get_standard_option
('group-list'),
327 requires
=> 'groups',
331 returns
=> { type
=> 'null' },
335 my ($username, $ruid, $realm) =
336 PVE
::AccessControl
::verify_username
($param->{userid
});
338 PVE
::AccessControl
::lock_user_config
(
341 my $usercfg = cfs_read_file
("user.cfg");
343 PVE
::AccessControl
::check_user_exist
($usercfg, $username);
345 $usercfg->{users
}->{$username}->{enable
} = $param->{enable
} if defined($param->{enable
});
347 $usercfg->{users
}->{$username}->{expire
} = $param->{expire
} if defined($param->{expire
});
349 PVE
::AccessControl
::delete_user_group
($username, $usercfg)
350 if (!$param->{append
} && defined($param->{groups
}));
352 if ($param->{groups
}) {
353 foreach my $group (split_list
($param->{groups
})) {
354 if ($usercfg->{groups
}->{$group}) {
355 PVE
::AccessControl
::add_user_group
($username, $usercfg, $group);
357 die "no such group '$group'\n";
362 $usercfg->{users
}->{$username}->{firstname
} = $param->{firstname
} if defined($param->{firstname
});
363 $usercfg->{users
}->{$username}->{lastname
} = $param->{lastname
} if defined($param->{lastname
});
364 $usercfg->{users
}->{$username}->{email
} = $param->{email
} if defined($param->{email
});
365 $usercfg->{users
}->{$username}->{comment
} = $param->{comment
} if defined($param->{comment
});
366 $usercfg->{users
}->{$username}->{keys} = $param->{keys} if defined($param->{keys});
368 cfs_write_file
("user.cfg", $usercfg);
369 }, "update user failed");
374 __PACKAGE__-
>register_method ({
375 name
=> 'delete_user',
379 description
=> "Delete user.",
382 [ 'userid-param', 'Realm.AllocateUser'],
383 [ 'userid-group', ['User.Modify']],
387 additionalProperties
=> 0,
389 userid
=> get_standard_option
('userid-completed'),
392 returns
=> { type
=> 'null' },
396 my $rpcenv = PVE
::RPCEnvironment
::get
();
397 my $authuser = $rpcenv->get_user();
399 my ($userid, $ruid, $realm) =
400 PVE
::AccessControl
::verify_username
($param->{userid
});
402 PVE
::AccessControl
::lock_user_config
(
405 my $usercfg = cfs_read_file
("user.cfg");
407 my $domain_cfg = cfs_read_file
('domains.cfg');
408 if (my $cfg = $domain_cfg->{ids
}->{$realm}) {
409 my $plugin = PVE
::Auth
::Plugin-
>lookup($cfg->{type
});
410 $plugin->delete_user($cfg, $realm, $ruid);
413 # Remove TFA data before removing the user entry as the user entry tells us whether
414 # we need ot update priv/tfa.cfg.
415 PVE
::AccessControl
::user_set_tfa
($userid, $realm, undef, undef, $usercfg, $domain_cfg);
417 delete $usercfg->{users
}->{$userid};
419 PVE
::AccessControl
::delete_user_group
($userid, $usercfg);
420 PVE
::AccessControl
::delete_user_acl
($userid, $usercfg);
421 cfs_write_file
("user.cfg", $usercfg);
422 }, "delete user failed");
427 __PACKAGE__-
>register_method ({
428 name
=> 'read_user_tfa_type',
429 path
=> '{userid}/tfa',
432 description
=> "Get user TFA types (Personal and Realm).",
435 ['userid-param', 'self'],
436 ['userid-group', ['User.Modify', 'Sys.Audit']],
440 additionalProperties
=> 0,
442 userid
=> get_standard_option
('userid-completed'),
446 additionalProperties
=> 0,
450 enum
=> [qw(oath yubico)],
451 description
=> "The type of TFA the users realm has set, if any.",
456 enum
=> [qw(oath u2f)],
457 description
=> "The type of TFA the user has set, if any.",
466 my ($username, undef, $realm) = PVE
::AccessControl
::verify_username
($param->{userid
});
469 my $domain_cfg = cfs_read_file
('domains.cfg');
470 my $realm_cfg = $domain_cfg->{ids
}->{$realm};
471 die "auth domain '$realm' does not exist\n" if !$realm_cfg;
474 $realm_tfa = PVE
::Auth
::Plugin
::parse_tfa_config
($realm_cfg->{tfa
})
475 if $realm_cfg->{tfa
};
477 my $tfa_cfg = cfs_read_file
('priv/tfa.cfg');
478 my $tfa = $tfa_cfg->{users
}->{$username};
481 $res->{realm
} = $realm_tfa->{type
} if $realm_tfa->{type
};
482 $res->{user
} = $tfa->{type
} if $tfa->{type
};
486 __PACKAGE__-
>register_method ({
487 name
=> 'token_index',
488 path
=> '{userid}/token',
490 description
=> "Get user API tokens.",
493 ['userid-param', 'self'],
494 ['perm', '/access/users/{userid}', ['User.Modify']],
498 additionalProperties
=> 0,
500 userid
=> get_standard_option
('userid-completed'),
505 items
=> $token_info_extend->({
506 tokenid
=> get_standard_option
('token-subid'),
508 links
=> [ { rel
=> 'child', href
=> "{tokenid}" } ],
513 my $userid = PVE
::AccessControl
::verify_username
($param->{userid
});
514 my $usercfg = cfs_read_file
("user.cfg");
516 my $user = PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
518 my $tokens = $user->{tokens
} // {};
519 return [ map { $tokens->{$_}->{tokenid
} = $_; $tokens->{$_} } keys %$tokens];
522 __PACKAGE__-
>register_method ({
523 name
=> 'read_token',
524 path
=> '{userid}/token/{tokenid}',
526 description
=> "Get specific API token information.",
529 ['userid-param', 'self'],
530 ['perm', '/access/users/{userid}', ['User.Modify']],
534 additionalProperties
=> 0,
536 userid
=> get_standard_option
('userid-completed'),
537 tokenid
=> get_standard_option
('token-subid'),
540 returns
=> get_standard_option
('token-info'),
544 my $userid = PVE
::AccessControl
::verify_username
($param->{userid
});
545 my $tokenid = $param->{tokenid
};
547 my $usercfg = cfs_read_file
("user.cfg");
549 return PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
552 __PACKAGE__-
>register_method ({
553 name
=> 'generate_token',
554 path
=> '{userid}/token/{tokenid}',
556 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!",
560 ['userid-param', 'self'],
561 ['perm', '/access/users/{userid}', ['User.Modify']],
565 additionalProperties
=> 0,
567 userid
=> get_standard_option
('userid-completed'),
568 tokenid
=> get_standard_option
('token-subid'),
569 expire
=> get_standard_option
('token-expire'),
570 privsep
=> get_standard_option
('token-privsep'),
571 comment
=> get_standard_option
('token-comment'),
575 additionalProperties
=> 0,
578 info
=> get_standard_option
('token-info'),
581 description
=> 'API token value used for authentication.',
588 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
589 my $tokenid = extract_param
($param, 'tokenid');
591 my $usercfg = cfs_read_file
("user.cfg");
593 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid, 1);
596 PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
597 raise_param_exc
({ 'tokenid' => 'Token already exists.' }) if defined($token);
599 my $generate_and_add_token = sub {
600 $usercfg = cfs_read_file
("user.cfg");
601 PVE
::AccessControl
::check_user_exist
($usercfg, $userid);
602 die "Token already exists.\n" if defined(PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid, 1));
604 my $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
605 $value = PVE
::TokenConfig
::generate_token
($full_tokenid);
608 $token->{privsep
} = defined($param->{privsep
}) ?
$param->{privsep
} : 1;
609 $token->{expire
} = $param->{expire
} if defined($param->{expire
});
610 $token->{comment
} = $param->{comment
} if $param->{comment
};
612 $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid} = $token;
613 cfs_write_file
("user.cfg", $usercfg);
616 PVE
::AccessControl
::lock_user_config
($generate_and_add_token, 'generating token failed');
618 return { info
=> $token, value
=> $value };
622 __PACKAGE__-
>register_method ({
623 name
=> 'update_token_info',
624 path
=> '{userid}/token/{tokenid}',
626 description
=> "Update API token for a specific user.",
630 ['userid-param', 'self'],
631 ['perm', '/access/users/{userid}', ['User.Modify']],
635 additionalProperties
=> 0,
637 userid
=> get_standard_option
('userid-completed'),
638 tokenid
=> get_standard_option
('token-subid'),
639 expire
=> get_standard_option
('token-expire'),
640 privsep
=> get_standard_option
('token-privsep'),
641 comment
=> get_standard_option
('token-comment'),
644 returns
=> get_standard_option
('token-info', { description
=> "Updated token information." }),
648 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
649 my $tokenid = extract_param
($param, 'tokenid');
651 my $usercfg = cfs_read_file
("user.cfg");
652 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
654 my $update_token = sub {
655 $usercfg = cfs_read_file
("user.cfg");
656 $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
658 my $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
660 $token->{privsep
} = $param->{privsep
} if defined($param->{privsep
});
661 $token->{expire
} = $param->{expire
} if defined($param->{expire
});
662 $token->{comment
} = $param->{comment
} if $param->{comment
};
664 $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid} = $token;
665 cfs_write_file
("user.cfg", $usercfg);
668 PVE
::AccessControl
::lock_user_config
($update_token, 'updating token info failed');
674 __PACKAGE__-
>register_method ({
675 name
=> 'remove_token',
676 path
=> '{userid}/token/{tokenid}',
678 description
=> "Remove API token for a specific user.",
682 ['userid-param', 'self'],
683 ['perm', '/access/users/{userid}', ['User.Modify']],
687 additionalProperties
=> 0,
689 userid
=> get_standard_option
('userid-completed'),
690 tokenid
=> get_standard_option
('token-subid'),
693 returns
=> { type
=> 'null' },
697 my $userid = PVE
::AccessControl
::verify_username
(extract_param
($param, 'userid'));
698 my $tokenid = extract_param
($param, 'tokenid');
700 my $usercfg = cfs_read_file
("user.cfg");
701 my $token = PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
703 my $update_token = sub {
704 $usercfg = cfs_read_file
("user.cfg");
706 PVE
::AccessControl
::check_token_exist
($usercfg, $userid, $tokenid);
708 my $full_tokenid = PVE
::AccessControl
::join_tokenid
($userid, $tokenid);
709 PVE
::TokenConfig
::delete_token
($full_tokenid);
710 delete $usercfg->{users
}->{$userid}->{tokens
}->{$tokenid};
712 cfs_write_file
("user.cfg", $usercfg);
715 PVE
::AccessControl
::lock_user_config
($update_token, 'deleting token failed');