On this page:

17.10User Management Endpoint

 

The User Management endpoint is used to administer user accounts within the Smile CDR user database.

17.10.1Search for Users (All Modules)

 
This method requires the VIEW_USERS permission.

This method will search for users matching a given set of criteria.


To invoke:

GET http://localhost:9000/user-management?pageNum=0&pageSize=10&searchTerm=admin

You may also add the following URL parameters:

  • pageNum=[int] – the page index to fetch (0-indexed)
  • pageSize=[int] – the page size to fetch
  • searchTerm=[string] – a search term to use (optional)

The server will produce a response resembling the following:

{
  "users": [
    {
      "pid": 2,
      "nodeId": "Master",
      "moduleId": "local_security",
      "username": "ADMIN",
      "familyName": "Admin",
      "givenName": "GenericUser",
      "lastActive": "2017-08-20T10:56:48.594-04:00",
      "accountLocked": false,
      "systemUser": false,
      "authorities": [
        {
          "permission": "ROLE_SUPERUSER"
        }
      ],
      "accountDisabled": false
    }
  ]
}

17.10.2Search for Users (Specific Module)

 
This method requires the VIEW_USERS permission.

This method will search for users matching a given set of criteria.


To invoke:

GET http://localhost:9000/user-management/{node_id}/{module_id}

You may also add the following URL parameters:

  • pageNum=[int] – the page index to fetch (0-indexed)
  • pageSize=[int] – the page size to fetch
  • searchTerm=[string] – a search term to use (optional)

The server will produce a response resembling the following:

{
  "users": [
    {
      "pid": 2,
      "nodeId": "Master",
      "moduleId": "local_security",
      "username": "ADMIN",
      "familyName": "Admin",
      "givenName": "GenericUser",
      "lastActive": "2017-08-20T10:56:48.594-04:00",
      "accountLocked": false,
      "systemUser": false,
      "authorities": [
        {
          "permission": "ROLE_SUPERUSER"
        }
      ],
      "accountDisabled": false
    }
  ]
}

17.10.3Create User

 
This method requires the CREATE_USER permission.

This method will create a new user record in the database.


To invoke:

POST http://localhost:9000/user-management/{node_id}/{module_id}

The following shows an example request body to create a user:

{
  "familyName": "Smith",
  "givenName": "John",
  "password": "thepassword",
  "username": "someuser",
  "authorities": [
    {
      "permission": "ROLE_FHIR_CLIENT_SUPERUSER_RO"
    }
  ]
}

The server responds with an HTTP 201 response such as the following:

{
  "pid": 102,
  "nodeId": "Master",
  "moduleId": "local_security",
  "username": "someuser",
  "familyName": "Smith",
  "givenName": "John",
  "accountLocked": false,
  "systemUser": false,
  "authorities": [
    {
      "permission": "ROLE_FHIR_CLIENT_SUPERUSER_RO"
    }
  ],
  "accountDisabled": false
}

Note the pid element that can be used to update this user further.

17.10.4Update User

 
This method requires the UPDATE_USER permission.

This method will update a user record in the database.


To invoke:

PUT http://localhost:9000/user-management/{node_id}/{module_id}/{user_pid}

The following shows an example request body to update a user:

{
  "familyName": "Smith",
  "givenName": "John",
  "password": "thepassword",
  "username": "someuser",
  "authorities": [
    {
      "permission": "ROLE_FHIR_CLIENT_SUPERUSER_RO"
    }
  ]
}

Note that the password will be left unchanged if it is not supplied in the request.

The server responds with an HTTP 200 response such as the following:

{
  "pid": 102,
  "nodeId": "Master",
  "moduleId": "local_security",
  "username": "someuser",
  "familyName": "Smith",
  "givenName": "John",
  "accountLocked": false,
  "systemUser": false,
  "authorities": [
    {
      "permission": "ROLE_FHIR_CLIENT_SUPERUSER_RO"
    }
  ],
  "accountDisabled": false
}

17.10.5Update Password

 
This method requires the UPDATE_USER permission.

This method will update a user's password but not modify any other details. It is intended for use cases where an administrative user needs to have access to update or reset another user's password.


To invoke:

PUT http://localhost:9000/user-management/{node_id}/{module_id}/{user_pid}/password

The following shows an example request body to update a user. Note that:

  • The currentPassword element is not required to be populated for this operation. If it is provided however, it will be verified and the password will not be changed if it is not correct.
  • The credentialExpiry element is not required to be populated for this operation. If it is populated, the new password will be set to expire at the given time. If it is not populated, the new password will be set to not expire.
{
  "currentPassword" : "(optional) the current password",
  "newPassword" : "the new password"
  "credentialExpiry": "(optional) ISO8601 encoded expiry time"
}

The server responds with an HTTP 200 response such as the following:

{
  "statusCode" : 200
}

17.10.6Update Own Password

 
This method requires the CHANGE_OWN_PASSWORD permission.

This method will update the authenticated user's own password but not modify any other details. It is intended for use cases where a user wants to change their own password.


To invoke:

PUT http://localhost:9000/password/change

The following shows an example request body to update a user. Note that:

  • The currentPassword element is required to be populated for this operation. It will be verified and the password will not be changed if it is not correct.
  • The credentialExpiry element is not required to be populated for this operation. If it is populated, the new password will be set to expire at the given time. If it is not populated, the new password will be set to not expire.
{
  "currentPassword" : "the current password",
  "newPassword" : "the new password",
  "credentialExpiry": "(optional) ISO8601 encoded expiry time"
}

The server responds with an HTTP 200 response such as the following:

{
  "statusCode" : 200
}

Note that if the current password is not correct, the system will fail with an HTTP 400 response similar to the following:

{
  "statusCode" : 400,
  "messages" : [ {
    "message" : "Incorrect current password"
  } ]
}

17.10.72FA: Create New Key

 
This method requires the CHANGE_OWN_TFA_KEY permission.

This method creates a new Two Factor Authentication key for the logged in user (the user that authenticated with the services). The created key will be in unconfirmed state until the user confirms it in a separate API call.

See Two Factor Authentication for more information on how this is used.


To invoke:

POST http://localhost:9000/user-management/2fa/create-new

The request body should have the following contents:

{ "style": "TOTP" }

The server responds with an HTTP 200 response such as the following:

{
  "success": true,
  "message": "A new key has been created. Please confirm this key to activate it before: 2019-07-10T21:24:05-04:00"
}

17.10.82FA: Generate QR Code

 
This method requires the CHANGE_OWN_TFA_KEY permission.

This method generates and returns a PNG image containing a QR code for the user's 2FA key. This PNG can then be displayed to a user so that they can scan it in an authenticator application and confirm their key to activate it.


To invoke:

GET http://localhost:9000/user-management/2fa/generate-qr-code

The server responds with an HTTP 200 response such as the following:

200 OK
Content-Type: image/png

[ ... bytes ... ]

17.10.92FA: Confirm Key

 
This method requires the CHANGE_OWN_TFA_KEY permission.

This method should be called by a user who has just created a new key and scanned the resulting QR code into their authenticator app. It takes the current code generated by the authenticator app as an input, and confirms (i.e. activates) the key if the code is correct.


To invoke:

POST http://localhost:9000/user-management/2fa/confirm-key

The request body should be content similar to the following:

{
  "code": 291638,
  "style": "TOTP"
}

The server responds with an HTTP 200 response such as the following:

{ "success": true }

17.10.102FA: Delete Key

 
This method requires the CHANGE_OWN_TFA_KEY permission.

This method deletes and deactivates the user's currently active 2FA key.


To invoke:

POST http://localhost:9000/user-management/2fa/delete-key

The request body should be content similar to the following:

{
  "style": "TOTP"
}

The server responds with an HTTP 200 response such as the following:

{ "success": true }