Gel des utilisateurs

Les administrateurs du serveur peuvent geler les utilisateurs via l’API d’administration. Un utilisateur gelé sera temporairement empêché de se connecter au serveur Parsec.

Ce mécanisme permet de bloquer automatiquement les utilisateurs qui ont été supprimés d’un service d’annuaire (comme OpenLDAP ou Active Directory), en attendant que l’administrateur de l’organisation les révoque. Il est exposé sous la forme de routes HTTP qui ne nécessitent qu’un jeton d’administration.

Note

L’opération de gel est effectuée par un administrateur du serveur et est réversible. L’opération de révocation est effectuée par un administrateur de l’organisation et n’est pas réversible ; il s’agit de la suppression définitive des droits de l’utilisateur au sein de l’organisation.

Route HTTP `/users`

Cette route est disponible sous administration/organisations/<raw_organization_id>/users et nécessite un jeton d’administration.

Il prend en charge la méthode GET qui liste les informations relatives à tous les utilisateurs, y compris :

Parsec ID
nom de l’utilisateur
adresse e-mail de l’utilisateur
statut de gel

Voici un exemple utilisant curl et jq :

$ curl https://$server/administration/organizations/$organization/users \
    -H "Authorization: Bearer $administration_token" | jq

Une requête réussie renvoie un objet JSON avec la structure suivante :

{
  "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"
    }
  ]
}

Route HTTP `/users/freeze`

Cette route est disponible sous administration/organisations/<raw_organization_id>/users/freeze et nécessite un jeton d’administration.

Il supporte la méthode POST qui modifie le statut frozen pour un utilisateur donné.

Voici un exemple de génération des données de la requête en utilisant jq :

$ DATA=$(jq -n --arg user_id "$user_id" --argjson frozen true '$ARGS.named')
$ echo $DATA
{
"user_id": "940a380aedd44127863d952a66cfce1e",
"frozen": true
}

La requête peut également utiliser le champ user_email au lieu de user_id pour identifier l’utilisateur de Parsec (voir la section note on user identification ci-dessous pour plus d’informations) :

$ DATA=$(jq -n --arg user_email "$user_email" --argjson frozen true '$ARGS.named')
$ echo $DATA
{
"user_email": "alice@example.com",
"frozen": true
}

Voici un exemple d’exécution de la requête en utilisant curl et jq :

$ curl https://$server/administration/organizations/$organization/users/freeze \
    -H "Authorization: Bearer $administration_token" \
    --request POST --data $DATA | jq

Une requête réussie renvoie un dictionnaire JSON similaire à celui ci-dessous :

{
  "frozen": true,
  "user_email": "alice@example.com",
  "user_id": "940a380aedd44127863d952a66cfce1e",
  "user_name": "Alice"
}

Traitement des erreurs HTTP

Les erreurs suivantes peuvent être retournées par les routes /users et /users/freeze :

404: Organization not found avec JSON body {"error": "not_found}
403: Invalid administration token avec JSON body {"error": "not_allowed"}
400: Wrong request format avec JSON body {"error": "bad_data"}

L’erreur suivante est retournée par la requête /users/freeze si l’utilisateur n’existe pas dans l’organisation :

404: User not found avec JSON body {"error": "user_not_found"}

Note sur l’identification de l’utilisateur

Il existe une différence subtile entre l’utilisation de l’ID utilisateur Parsec ou de l’adresse e-mail pour identifier un utilisateur.

Le user ID identifie de manière unique un utilisateur au sein du serveur Parsec, quelle que soit son organisation. Lorsqu’un utilisateur est révoqué, son ID identifie l’utilisateur révoqué.
L”adresse électronique identifie un utilisateur actif (c’est-à-dire non révoqué) au sein d’une organisation. Lorsqu’un utilisateur est révoqué, son adresse électronique peut être réutilisée pour rejoindre l’organisation.

Cela signifie qu’au fil du temps, une adresse électronique peut être partagée entre plusieurs identifiants d’utilisateurs, qu’ils appartiennent à des organisations différentes ou à la même organisation s’ils ont été révoqués.

Considérons le scénario suivant :

Org 1	Org 2
ID 1 alice@mail.com (révoqué)	ID 4 bob@mail.com (actif)
ID 2 bob@mail.com (actif)	ID 5 alice@mail.com (actif)
ID 3 alice@mail.com (actif)

Le statut frozen spécifié dans la requête POST est toujours associé à un ID d’utilisateur Parsec, même si une adresse e-mail est spécifiée.

En ce qui concerne le scénario précédent, voici quelques requêtes possibles et leurs résultats : - Gel de l’utilisateur avec ID 1 : n’aura aucune conséquence puisque l’utilisateur est déjà révoqué. - Gel de l’utilisateur avec ID 4 : l’utilisateur sera effectivement gelé. Son statut actif est maintenu en cas de déblocage. - Gel de l’utilisateur avec l’email alice@mail.com dans Org 1 : l’utilisateur avec l’ID 3 sera gelé (l’utilisateur avec ID 1 n’est pas pris en compte car déjà révoqué).

Avertissement

Notez que si un utilisateur est révoqué d’une organisation puis réinvité avec la même adresse électronique, son statut gelé antérieur ne sera pas appliqué au nouvel utilisateur.