The User Management endpoint is used to administer user accounts within the Smile CDR user database.
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 fetchsearchTerm=[string] – (optional) a search term to useincludeDisabled=[string] – (optional) should disabled user accounts be included in the search results. Valid values are:
sort=[string] – (optional) How should results be sorted. Valid values are:
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
}
]
}
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 fetchsearchTerm=[string] – (optional) a search term to useincludeDisabled=[string] – (optional) should disabled user accounts be included in the search results. Valid values are:
sort=[string] – (optional) How should results be sorted. Valid values are:
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
}
]
}
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.
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
}
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:
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.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
}
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:
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.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"
} ]
}
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
}
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"
}
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 ... ]
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 }
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 }
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
}