Smile CDR v2024.05.PRE
On this page:

35.14.1User Management Endpoint

 

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

35.14.2Search 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](optional) a search term to use
  • includeDisabled=[string](optional) should disabled user accounts be included in the search results. Valid values are:
    • ENABLED – Include only enabled users
    • DISABLED – Include only disabled users
    • BOTH – Include all users
  • sort=[string](optional) How should results be sorted. Valid values are:
    • UNORDERED – Do not sort
    • USERNAME_ASC – Sort by username (ascending)
    • USERNAME_DESC – Sort by username (descending)
    • FAMILY_NAME_ASC – Sort by family name (ascending)
    • FAMILY_NAME_DESC – Sort by family name (descending)
    • GIVEN_NAME_ASC – Sort by given name (ascending)
    • GIVEN_NAME_DESC – Sort by given name (descending)
    • PID_ASC – Sort by PID (ascending)
    • PID_DESC – Sort by PID (descending)

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

35.14.3Search 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](optional) a search term to use
  • includeDisabled=[string](optional) should disabled user accounts be included in the search results. Valid values are:
    • ENABLED – Include only enabled users
    • DISABLED – Include only disabled users
    • BOTH – Include all users
  • sort=[string](optional) How should results be sorted. Valid values are:
    • UNORDERED – Do not sort
    • USERNAME_ASC – Sort by username (ascending)
    • USERNAME_DESC – Sort by username (descending)
    • FAMILY_NAME_ASC – Sort by family name (ascending)
    • FAMILY_NAME_DESC – Sort by family name (descending)
    • GIVEN_NAME_ASC – Sort by given name (ascending)
    • GIVEN_NAME_DESC – Sort by given name (descending)
    • PID_ASC – Sort by PID (ascending)
    • PID_DESC – Sort by PID (descending)

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

35.14.4Create 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"
    },
    {
      "permission": "FHIR_READ_ALL_IN_COMPARTMENT",
      "argument": "Patient/123"
    }
  ]
}

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"
    },
    {
      "permission": "FHIR_READ_ALL_IN_COMPARTMENT",
      "argument": "Patient/123"
    }
  ],
  "accountDisabled": false
}

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

35.14.5Update 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"
    },
    {
      "permission": "FHIR_READ_ALL_IN_COMPARTMENT",
      "argument": "Patient/123"
    }
  ]
}

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"
    },
    {
      "permission": "FHIR_READ_ALL_IN_COMPARTMENT",
      "argument": "Patient/123"
    }
  ],
  "accountDisabled": false
}

35.14.6Update 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
}

35.14.7Update 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/user-management/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"
  } ]
}

35.14.8Update Own Default Launch Contexts

 
This method requires the CHANGE_OWN_DEFAULT_LAUNCH_CONTEXTS permission.

This method will update the SMART default launch contexts associated with the logged in user's account. This can be used to achieve a simple form of context sharing across SMART applications that are all authorized using a single Smile CDR SMART Outbound Security module.


To invoke:

PUT http://localhost:9000/user-management/default_launch_contexts/change

The following shows an example request body, which should be of type UserDetailsChangeLaunchContextJson. The input is treated as a complete snapshot, meaning that any default launch contexts already associated with the account will be removed if they are not present in the input to this operation.

{
  "contexts": [
    {
      "contextType": "patient",
      "resourceId": 123
    }
  ]
}

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

{
  "statusCode" : 200
}

35.14.92FA: 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"
}

35.14.102FA: 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 ... ]

35.14.112FA: 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 }

35.14.122FA: 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 }

35.14.13Invalidate All Sessions

 
This method requires the UPDATE_USER permission unless it is being called by the actual user referred to by the method parameters.

This method revokes all active Access Tokens and Refresh Tokens for the given user. Note that this applies only to tokens that were issued by Smile CDR via the SMART Outbound Security module.


To invoke:

POST http://localhost:9000/user-management/{node_id}/{module_id}/invalidate-all-sessions?username={username}

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

{
  "accessTokenCount": 1,
  "refreshTokenCount": 1
}