Utilisateurs¶

Utilisateurs¶

Cette section couvre les méthodes de ressources de l'utilisateur.

/api/users

Requête de l'utilisateur¶

La ressource utilisateurs offre des paramètres de requête supplémentaires en plus des paramètres standard (par exemple, la pagination). Pour rechercher des utilisateurs dans la ressource vous pouvez utiliser les paramètres suivants.

Tableau : Paramètres de requête de l'utilisateur

Une requête pour un maximum de 10 utilisateurs avec "konan" comme prénom ou nom de famille (sensible à la casse) qui ont un sous-ensemble d'autorisations par rapport à l'utilisateur actuel :

/api/users?query=konan&authSubset=true&pageSize=10

Récupérer tous les comptes d'utilisateurs qui ont été initialement auto-inscrits :

/api/users?selfRegistered=true

Requête de l'utilisateur par identifiant¶

La syntaxe suivante permet d'obtenir des informations complètes sur un utilisateur ayant un identifiant particulier.

/api/users/{id}

Voici un exemple d'identifiant particulier :

/api/users/OYLGMiazHtW

Recherche d'utilisateurs¶

L'API de recherche d'utilisateurs propose un système de récupération des utilisateurs lorsque la réponse comporte un minimum d'informations. Aucune autorité spécifique n'est requise et elle permet aux clients de rechercher des informations telles que le prénom et le nom de famille de l'utilisateur, sans pour autant révéler des informations potentiellement sensibles.

/api/userLookup

Le système de recherche de l'utilisateur comporte deux méthodes.

Recherche des utilisateurs par identifiant¶

Vous pouvez effectuer une recherche d'utilisateur par identifiant en utilisant la requête API suivante :

GET /api/userLookup/{id}

L'ID de l'utilisateur sera recherché par rapport aux propriétés d'utilisateur suivantes dans l'ordre indiqué :

• UID
• UUID
• Nom d'utilisateur

Voici donc un exemple de requête :

/api/userLookup/QqvaU7JjkUV

La réponse comportera un minimum d'informations relatives à l'utilisateur.

{
  "id": "QqvaU7JjkUV",
  "nom d'utilisateur": "nkono",
  "prénom": "Thomas",
  "nom de famille": "Nkono",
  "nom affiché": "Thomas Nkono"
}

Requête de recherche d'utilisateurs¶

Vous pouvez réaliser une requête des utilisateurs à partir de la requête API suivante :

GET /api/userLookup?query={string}

Le paramètre de requête query est obligatoire. La chaîne de requête query sera comparée aux propriétés utilisateur suivantes :

• Prénom
• Nom
• Adresses électronique
• Nom d'utilisateur

En plus du paramètre query, la recherche peut être restreinte par le paramètre orgUnitBoundary comme décrit dans le tableau des paramètres pour les utilisateurs ci-dessus.

Voici donc un exemple de requête :

/api/userLookup?query=John

La réponse comportera des informations relatives aux utilisateurs et correspondants à la requête.

{
  "utilisateurs": [
    {
      "id": "DXyJmlo9rge",
      "nom d'utilisateur": "jbarnes",
      "prénom": "John",
      "nom de famille": "Barnes",
      "nom affiché": "John Barnes"
    },
    {
      "id": "N3PZBUlN8vq",
      "nom d'utilisateur": "jkamara",
      "prénom": "John",
      "nom de famille": "Kamara",
      "nom affiché": "John Kamara"
    }
  ]
}

Créer et mettre à jour un compte utilisateur¶

La création et la mise à jour des utilisateurs sont prises en charge par l'API. Une charge utile de base pour créer un utilisateur ressemble à l'exemple ci-dessous. Notez que le mot de passe sera envoyé en texte clair, n'oubliez donc pas d'activer SSL/HTTPS pour le transport réseau.

{
  "identifiant": "Mj8balLULKp",
  "Prénom": "John",
  "nom ": "Doe",
  "email": "johndoe@mail.com",
  "informations d'identification de l'utilisateur": {
    "identifiant": "lWCkJ4etppc",
    "infoUtilisateur": {
    "identifiant": "Mj8balLULKp"
  },
  "nom d'utilisateur": "johndoe123",
  "mot de passe": "Your-password-123",
  "skype": "john.doe",
  "telegram": "joh.doe",
  "whatsApp": "+1-541-754-3010",
  "facebookMessenger": "john.doe",
  "avatar": {
    "identifiant": "<fileResource id>"
  },
  "rôles d'utilisateur": [
    {
      "identifiant": "Ufph3mGRmMo"
    }
  ]
  },
  "unités d'organisation": [
    {
      "identifiant": "Rp268JB6Ne4"
    }
  ],
  "groupes d'utilisateurs": [
    {
      "identifiant": "wl5cDMuUhmF"
    }
  ]
}

curl -X POST -d @u.json "http://server/api/33/users" -u user:pass
  -H "Content-Type: application/json"

Dans la charge utile de création d'utilisateurs, les groupes d'utilisateurs ne sont pris en charge que lors de l'importation ou du POSTing d'un seul utilisateur à la fois. Si vous tentez de créer plus d'un utilisateur tout en spécifiant des groupes d'utilisateurs, vous ne recevrez pas d'erreur et les utilisateurs seront créés, mais aucun groupe d'utilisateurs ne sera affecté. Ceci est prévu et limité en raison de la relation de plusieurs à plusieurs entre les utilisateurs et les groupes d'utilisateurs, les groupes d'utilisateurs étant propriétaires de la relation. Pour mettre à jour ou créer plusieurs utilisateurs et leurs groupes d'utilisateurs, envisagez un programme pour POSTER un à la fois, ou POSTER tous les utilisateurs suivi d'une autre action pour mettre à jour leurs groupes d'utilisateurs tout en spécifiant les identifiants du nouvel utilisateur.

Lors de la création d'un utilisateur, la charge utile peut également contenir les paramètres de l'utilisateur. Ceux-ci sont ajoutés en tant qu'objet settings à l'objet racine. Chaque paire clé-valeur devient un membre de l'objet settings, par exemple :

{
    "id": "Mj8balLULKp",
    "Prénom": "John",
    "Nom": "Doe",
    "paramètres": {
        "keyUiLocale": "de"
    },
    //...
}

Après la création de l'utilisateur, une entête Location est renvoyée avec l'identifiant nouvellement généré (vous pouvez également fournir le vôtre en utilisant le point d'extrémité /api/system/id). La même charge utile peut alors être utilisée pour faire des mises à jour, mais n'oubliez pas d'utiliser PUT au lieu de POST et le point d'extrémité est désormais /api/users/ID.

curl -X PUT -d @u.json "http://server/api/33/users/ID" -u user:pass
  -H "Content-Type: application/json"

Pour plus d'informations sur l'ensemble des données disponibles, voir /api/schemas/user.

Pour plus d'informations sur le téléchargement et la récupération des avatars des utilisateurs, veuillez consulter le point d'extrémité /fileResources.

Invitations pour les comptes d'utilisateurs¶

L'API Web permet d'inviter des personnes à créer des comptes d'utilisateur par le biais de la ressource invite. Pour créer une invitation, vous devez POSTER un utilisateur au format XML ou JSON à la ressource "invite". Un nom d'utilisateur spécifique peut être imposé en définissant le nom d'utilisateur dans l'entité postée. En omettant le nom d'utilisateur, la personne pourra le spécifier elle-même. Le système enverra une invitation par courrier électronique. Il faut pour cela que les paramètres de messagerie soient correctement configurés.

La ressource "invite" est utile pour permettre en toute sécurité à des personnes de créer des comptes sans que personne d'autre ne connaisse le mot de passe ou en transférant le mot de passe en texte clair. La charge utile à utiliser pour l'invitation est la même que pour la création d'utilisateurs. Un exemple de charge utile en JSON ressemble à ceci :

{
  "prénom": "John",
  "nom": "Doe",
  "email": "johndoe@mail.com",
  "informations d'identification de l'utilisateur": {
    "nom d'utilisateur": "johndoe",
    "roles d'utilisateur": [{
      "id": "Euq3XfEIEbx"
    }]
  },
  "unités d'organisation": [ {
    "id": "ImspTQPwCqd"
  } ],
  "groupes d'utilisateurs": [ {
    "id": "vAvEltyXGbD"
  }]
}

L'entité d'invitation de l'utilisateur peut être affichée comme suit :

curl -d @invite.json "localhost/api/33/users/invite" -u admin:district
  -H "Content-Type:application/json"

Pour envoyer des invitations à plusieurs utilisateurs en même temps, vous devez utiliser un format légèrement différent. Pour JSON :

{
  "utilisateurs": [ {
    "prénom": "John",
    "nom": "Doe",
    "email": "johndoe@mail.com",
    "informations d'identification de l'utilisateur": {
      "nom d'utilisateur": "johndoe",
      "rôles d'utilisateur": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "unités d'organisation": [ {
      "id": "ImspTQPwCqd"
      } ]
    }, {
    "prénom": "Tom",
    "nom": "Johnson",
    "email": "tomj@mail.com",
    "informations d'identification de l'utilisateur": {
      "rôles d'utilisateur": [ {
        "id": "Euq3XfEIEbx"
      } ]
    },
    "unités d'organisation": [ {
      "id": "ImspTQPwCqd"
      } ]
    }
  ]
}

Pour créer plusieurs invitations, vous pouvez envoyer la charge utile à la ressource api/users/invites comme ceci :

curl -d @invites.json "localhost/api/33/users/invites" -u admin:district
  -H "Content-Type:application/json"

Certaines conditions doivent être remplies pour que les invitations à ouvrir un compte d'utilisateur soient envoyées :

• Le serveur SMTP doit être configuré correctement sur le serveur.

• L'utilisateur à inviter doit avoir indiqué un e-mail valide.

• Si le nom d'utilisateur est spécifié, il ne doit pas être déjà pris par un autre utilisateur existant.

Si l'une de ces conditions n'est pas remplie, la ressource invitée renvoie un code d'état 409 Conflict accompagné d'un message descriptif.

User login (Experimental)¶

This endpoint is not meant for external use, unless you are implementing a custom login app, which you probably should not do, unless you have a very good reason.

A user can log in and get a session cookie with the following example:
POST /api/auth/login
with JSON body:

{
    "username": "username",
    "password": "password",
    "twoFactorCode": "two_factor_code"
}

{
    "loginStatus": "SUCCESS",
    "redirectUrl": "/dhis-web-dashboard/"
}

Invitation à confirmer le compte utilisateur (expérimental)¶

Important
Avant de confirmer une invitation, il faut qu'un utilisateur administrateur configure l'utilisateur et lui envoie un lien d'invitation. Cette condition préalable ajoute également quelques données nécessaires dans la table de la base de données userinfo ou informations d'utilisateur (idToken, restoreToken, restoreExpiry) pour cet utilisateur, afin de terminer l'invitation.

Un utilisateur peut confirmer une invitation via le point d'extrémité suivant : POST /api/auth/invite ; avec un corps JSON :

{
    "username": "TestUser",
    "firstName": "Test",
    "surname": "User",
    "password": "Test123!",
    "email": "test@test.com",
    "phoneNumber": "123456789",
    "g-recaptcha-response": "recaptchaResponse",
    "token": "aWRUb2tlbjpJRHJlc3RvcmVUb2tlbg=="
}

Note La valeur g-recaptcha-response serait remplie par l'utilisation de l'interface utilisateur principale de l'application de connexion. Le champ token attend une valeur encodée en Base64. Dans cet exemple, décodé, c'est idToken:IDrestoreToken. Celui-ci sera envoyé par email à l'utilisateur invité (il est en fait créé en interne (et rempli dans la base de données) durant l'opération /api/users/invite).

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "OK",
    "httpStatusCode": 200,
    "status": "OK",
    "message": "Account updated"
}

Enregistrement d'un compte d'utilisateur (expérimental)¶

Un utilisateur peut s'enregistrer directement via le point d'extrémité suivant : POST /api/auth/registration avec un corps JSON :

{
    "username": "testSelfReg",
    "firstName": "test",
    "surname": "selfReg",
    "password": "P@ssword123",
    "email": "test@test.com",
    "phoneNumber": "12345oooo",
    "g-recaptcha-response": "recap response"
}

Voici un exemple de réponse après une opération réussie :

{
    "httpStatus": "Created",
    "httpStatusCode": 201,
    "status": "OK",
    "message": "Account created"
}

L'utilisateur a oublié son mot de passe (expérimental)¶

Ce point d'extrémité est utilisé pour déclencher le flux de mots de passe oubliés. Il peut être déclenché après que soient fournis le nom d'utilisateur ou l'adresse électronique de l'utilisateur dont le mot de passe doit être réinitialisé. Cela se fait via une requête POST /api/auth/forgotPassword avec un corps JSON comme suit :

{
    "emailOrUsername": "testUsername1"
}

Une réponse après une opération réussie renvoie un 200 OK vide. Cela devrait déclencher l'envoi d'un email à l'utilisateur pour lui permettre de réinitialiser son mot de passe.

Réinitialisation du mot de passe de l'utilisateur (expérimental)¶

Lorsqu'un utilisateur reçoit un email contenant un lien pour réinitialiser son mot de passe, celui-ci contient un token qui peut être utilisé pour l'opération. POST /api/auth/passwordReset avec un corps JSON :

{
    "newPassword": "ChangeMe123!",
    "resetToken": "token-value-from-email-link"
}

Une réponse après une opération réussie renvoie un 200 OK vide. L'utilisateur devrait maintenant pouvoir se connecter en utilisant son nouveau mot de passe.

Réplication de l'utilisateur¶

Pour reproduire un utilisateur, vous pouvez utiliser la ressource replica. Reproduire un utilisateur peut être utile pour déboguer ou reproduire des problèmes signalés par un particulier. Vous devez fournir un nouveau nom d'utilisateur et un nouveau mot de passe à l'utilisateur reproduit, que vous allez utiliser pour vous authentifier ultérieurement. Notez que vous avez besoin de l'autorisation ALL pour effectuer cette action. Pour reproduire un utilisateur, vous vous pouvez envoyer une charge utile JSON comme ci-dessous :

{
  "username": "user_replica",
  "password": "SecretPassword"
}

Cette charge utile peut être envoyée à la ressource réplica, où vous fournissez l'identifiant de l'utilisateur à répliquer dans l'URL :

/api/33/users/<uid>/replica

Voici un exemple de reproduction d'un utilisateur à l'aide de curl :

curl -d @replica.json "localhost/api/33/users/N3PZBUlN8vq/replica"
  -H "Content-Type:application/json" -u admin:district

Réinitialiser le mot de passe de l'utilisateur¶

Les administrateurs utilisateurs (disposant des droits appropriés) peuvent réinitialiser le compte d'un autre utilisateur en déclenchant la récupération du mot de passe. Une fois l'opération déclenchée, un e-mail contenant un lien de récupération est envoyé à l'utilisateur. Les utilisateurs qui suivent le lien accèdent à un formulaire qui leur permet de définir un nouveau mot de passe.

Pour déclencher ce flux de travail pour l'utilisateur tH7WIiIJ0O3, utilisez :

POST /api/37/users/tH7WIiIJ0O3/reset

Désactiver et activer des comptes d'utilisateurs¶

Les comptes d'utilisateurs peuvent être marqués comme désactivés. Un utilisateur désactivé ne peut plus se connecter.

Pour marquer un utilisateur avec l'UID tH7WIiIJ0O3 comme désactivé (nécessite un utilisateur avec les droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/disabled

Pour permettre à un utilisateur désactivé d'utiliser à nouveau l'outil en question (l'utilisateur doit disposer des droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/enabled

Expiration de l'utilisateur¶

Une date d'expiration peut être définie pour un compte d'utilisateur. Elle marque le moment à partir duquel le compte d'utilisateur a expiré et ne peut plus être utilisé. L'utilisateur dont le compte a expiré ne peut plus se connecter.

Pour mettre à jour la date d'expiration de l'utilisateur avec l'UID tH7WIiIJ0O3 et la mettre à la date 2021-01-01 (nécessite un utilisateur avec les droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/expired?date=2021-01-01

Pour désactiver la date d'expiration afin que le compte n'expire jamais utiliser en conséquence (nécessite un utilisateur disposant des droits appropriés) :

POST /api/36/users/tH7WIiIJ0O3/unexpired

Flux de travail pour l'approbation des données des utilisateurs¶

Pour connaître les flux de travail et les niveaux d'approbation des données auxquels un utilisateur peut accéder, vous pouvez utiliser la ressource dataApprovalWorkflows comme suit :

GET /api/users/{id}/dataApprovalWorkflows

Passage d'un compte d'utilisateur à un autre tout en étant connecté au même compte qui fourni l'identité¶

If linked accounts are enabled in dhis.conf and a user has logged in via OIDC, then it is possible for the user to switch between DHIS2 accounts that are linked to the same identity provider account using this API call:

GET /dhis-web-commons-security/logout.action?current={current_username}&switch={username_to_switch_to}

Cette opération a pour effet de déconnecter l'utilisateur actuel et de connecter le nouvel utilisateur. L'opération semble transparente, sauf que le nouvel utilisateur se retrouve sur la page par défaut de l'instance DHIS2.

Notez que cet appel API sera probablement modifié à l'avenir, mais que sa fonction générale restera la même.

Pour consulter la liste des utilisateurs vers lesquels il est possible de basculer, utilisez cet appel API :

GET /api/account/linkedAccounts

Informations sur l'utilisateur actuel¶

Pour obtenir des informations sur l'utilisateur actuellement authentifié et ses associations avec d'autres ressources, vous pouvez utiliser la ressource me (vous pouvez également l'appeler par son ancien nom currentUser). Les ressources liées à l'utilisateur actuel fournissent des informations utiles lors de la création de clients, par exemple pour la saisie de données et la gestion des utilisateurs. Les paragraphes suivants décrivent ces ressources et leur objectif.

Fournit des informations de base sur l'utilisateur sous lequel vous êtes actuellement connecté. en tant qu'utilisateur, y compris le nom d'utilisateur, les informations d'identification de l'utilisateur, les unités d'organisation affectées:

/api/me

Donne des informations sur les messages non lus et les interprétations :

/api/me/tableau de bord

Pour modifier le mot de passe, ce point d'extrémité peut être utilisé pour valider le mot de passe nouvellement saisi. le nouveau mot de passe. La validation du mot de passe sera effectuée sur la base des PasswordValidationRules configurées dans le système. Ce point d'extrémité prend en charge POST et la chaîne du mot de passe doit être envoyée dans le corps de POST.

/api/me/valider le mot de passe

Lors d'un changement de mot de passe, ce point final (support POST) peut être utilisé pour vérifier l'ancien mot de passe. La chaîne du mot de passe doit être envoyée dans le corps du POST.

/api/me/verifier le mot de passe

Renvoie l'ensemble des autorisations accordées à l'utilisateur actuel :

/api/me/authorisation

Renvoie vrai ou faux, indiquant si l'utilisateur actuel a reçu l'autorisation <auth> donnée:

/api/me/authorisation/<auth>

Indique les niveaux d'approbation des données correspondant à l'utilisateur actuel :

/api/me/Niveaux d'approbation des données

Indique les flux de travail d'approbation des données accessibles à l'utilisateur actuel. Pour chaque flux de travail, indique les niveaux d'approbation des données que l'utilisateur peut voir, et les autorisations dont il dispose à chaque niveau :

/api/me/dataApprovalWorkflows