Freeze users
It is possible for server administrators to freeze specific Parsec users.
Frozen users will be temporarily blocked from connecting to the Parsec server while waiting for an organization administrator to actually revoke them. This operation is thus not part of the Parsec revocation system (i.e. the definitive removal of the user’s rights).
The freeze mechanism allows to automatically block users who have been deleted from a directory service (such as OpenLDAP
or AD
), as it is exposed in the form of HTTP routes that only requires an administration token.
It is also exposed as a command line interface (CLI) command, see the section about CLI commands.
HTTP users
route
This route is made available as /administration/organizations/<raw_organization_id>/users
and requires an administration token.
It only supports the GET
method which lists information for all users, including:
Parsec ID
user name
user email
frozen status
Here’s an example using curl
and jq
:
$ curl https://$server/administration/organizations/$organization/users \ -H "Authorization: Bearer $administration_token" | jq
A successful request returns a JSON object with the following structure:
{ "users": [ { "user_name": "Alice", "frozen": true, "user_email": "alice@example.com", "user_id": "940a380aedd44127863d952a66cfce1e" }, { "user_name": "Bob", "frozen": false, "user_email": "bob@example.com", "user_id": "7d04b0df51a74158b35b6386eecdf4e0" } ] }
HTTP users/freeze
route
This route is made available as /administration/organizations/<raw_organization_id>/users/freeze
and requires an administration token.
It only supports the POST
method which modifies the frozen
status for a given user.
Here’s an example of generating the request data using jq
:
$ DATA=$(jq -n --arg user_id "$user_id" --argjson frozen true '$ARGS.named') $ echo $DATA { "user_id": "940a380aedd44127863d952a66cfce1e", "frozen": true }
The request can also use the user_email
field instead of user_id
to identify the Parsec user (see the notes on user identification section below for more information):
$ DATA=$(jq -n --arg user_email "$user_email" --argjson frozen true '$ARGS.named') $ echo $DATA { "user_email": "alice@example.com", "frozen": true }
Here’s an example of running the request using curl
and jq
:
$ curl https://$server/administration/organizations/$organization/users/freeze \ -H "Authorization: Bearer $administration_token" \ --request POST --data $DATA | jq
A successful request returns a JSON dictionary similar to the one below:
{ "frozen": true, "user_email": "alice@example.com", "user_id": "940a380aedd44127863d952a66cfce1e", "user_name": "Alice" }
Notes on user identification
There is a subtle difference between the two ways to identify a user. At any given time, an email address can be used to uniquely identify a non-revoked user from a given organization. In contrast, a Parsec user ID identifies uniquely any user from all organizations in the Parsec server, including revoked users. This means that over time, an email address can identify different Parsec users with different Parsec IDs, even from the same organization.
The frozen status configured by the POST
method is specifically associated with the Parsec user ID, regardless of the identification method used in the request body. This has the following consequence: if a user is revoked and then a new user is created with the same email address, the frozen status will not be applied to the new user.
HTTP Error handling
The following errors can be returned by the both the users
and users/freeze
routes:
Organization not found:
404
with JSON body{"error": "not_found}
Invalid administration token:
403
with JSON body{"error": "not_allowed"}
Wrong request format:
400
with JSON body{"error": "bad_data"}
Another error can also be returned when the users/freeze
request contains a user that does not exist in the organization:
User not found:
404
with JSON body{"error": "user_not_found"}
CLI list_users
and freeze_user
commands
The list_users
command lists all users from a given organization, including their frozen status:
$ parsec core list_users -B "parsec://$server" -T $administration_token $organization • Alice <alice@example.com> - Parsec ID: 67ee640058aa45ca9281717c866baa06 - Status: Not frozen • Bob <bob@example.com> - Parsec ID: 0d22530361484b86b28e5b2c3a089772 - Status: Frozen • David <david@example.com> - Parsec ID: 1f1b81052fa947babdbacd6b147b3622 - Status: Not Frozen
The freeze_user
command allows to freeze a user from a given organization:
$ parsec core freeze_user -B "parsec://$server" -T $administration_token $organization $user_id David <david@example.com> - Parsec ID: 1f1b81052fa947babdbacd6b147b3622 - Status: Frozen
It can also be used to unfreeze a given user:
$ parsec core freeze_user -B "parsec://$server" -T $administration_token --unfreeze $organization $user_id David <david@example.com> - Parsec ID: 1f1b81052fa947babdbacd6b147b3622 - Status: Not frozen
The provided $user
can either be a parsec ID or an email address. Use the --help
for more information.