Skip to main content

User

A User is a non-encryptable, root-level entity that represents an actor that can log in to the system and perform actions according to their permissions.

Only a user that is a data owner (i.e. is associated to a HealthcareParty, Patient, or Device) and has initialized their own encryption keys can perform operations on the encryptable fields of encryptable entities. A user that is an admin or that has the correct permission can access encryptable entities, but they will only be able to read and write the non-encryptable fields.

For more information, check the explanation on data owners and access control.

Login Credentials​

In order to login, a user must provide valid credentials (namely, a login and a password) to the Cardinal SDK. Any of these field of the User entity is valid as login:

  • id
  • login
  • email
  • mobilePhone

As for the password, it is possible both to set a password (in the passwordHash field) or to use a temporary token.

Updating a user's login identifiers​

You can change the email, mobile phone, and password of a user with a regular modifyUser, but this requires the latest revision of the user, and may fail if the user is modified concurrently (for example by a SmartAuthProvider that updates the authentication tokens of the user while performing the request). For this reason, the user API provides dedicated methods that don't require the revision of the user:

  • modifyUserEmail(userId, newEmail, previousEmail) and modifyUserMobilePhone(userId, newMobilePhone, previousMobilePhone) (since SDK 2.2.0) replace the email or mobile phone of the user.
  • removeUserMobilePhone(userId, previousMobilePhone) (since SDK 2.11.0) removes the mobile phone of the user.
  • modifyUserPassword(userId, newPassword) (since SDK 2.2.0) sets a new password for the user.

Instead of the revision, the email and mobile phone methods take the value you expect to be currently stored in the user (the previous parameters are nullable, but not optional): if it doesn't match the stored value, the method fails with a RevisionConflictException.

modifyUserPassword doesn't require the previous password, so you can also use it to implement a "forgot password" flow. However, changing the password of a user is a sensitive operation that requires an elevated security context, so you should use it with an SDK initialized with a SmartAuthProvider (for example through an authentication secret provider) that can provide the required credentials when needed.

All these methods except removeUserMobilePhone also have an in-group variant, which takes the id of the group of the user as first parameter. To change the roles of a user, see modify user roles.

import com.icure.cardinal.sdk.CardinalSdk
import com.icure.cardinal.sdk.model.User

suspend fun updateLoginIdentifiers(
	sdk: CardinalSdk,
	userId: String,
	newEmail: String,
	newPassword: String
): User {
	val user = sdk.user.getUser(userId)!!
	// Fails with a RevisionConflictException if the email of the user is no longer user.email
	sdk.user.modifyUserEmail(userId, newEmail, user.email)
	if (user.mobilePhone != null) {
		sdk.user.removeUserMobilePhone(userId, user.mobilePhone)
	}
	return sdk.user.modifyUserPassword(userId, newPassword)
}

Roles​

The roles assigned to a User are stored in a nested object inside the systemMetadata property. It has 3 properties:

  • isAdmin is a boolean field that is true if the user is an admin.
  • roles is a set of the names of all the roles assigned to the user.
  • inheritsRoles is a boolean field that is true if the user has no role set and so inherits the roles from the group configuration.

Any update to this property will be prohibited by the backend. To learn how to update the roles on a user, check this how to.

Data Owner Users​

A User is a Data Owner User if exactly one of the following is true:

  • They have the id of a valid HealthcareParty in the healthcarePartyId field.
  • They have the id of a valid Patient in the patientId field.
  • They have the id of a valid Device in the deviceId field.
caution

A User can be associate either to a HealthcareParty, or to a Patient, or to a Device, and it cannot be associated to more than one of those entities.

When a Data Owner logs in, the SDK loads their available encryption keys or creates new one if no key is available. Then, the user will be able to create, modify and search encrypted data. You can read more about data owner users here

Properties​

Below you will find an explanation of the most commonly used properties in the entity that are not among the shared fields. For a full list, check the reference documentation (🚧).

authenticationTokens​

Contains all the active authentication tokens for the user, where the hash of the token is replaced by the character *.

This field is useful to check how many tokens are currently active and their duration, and it can be used to remove an active token, by deleting it from the map.

While it is possible to manually creating a token by adding it to this map, it is preferable to use the getToken method of the SDK. More information about application tokens can be found in this how to.

deviceId​

The id of the Device associated to this User. If this field is not null, then the healthcarePartyId and patientId fields should be null.

info

A User where this field is not null is a Data Owner User.

email​

The email of the User. It can be used as username to log in.

groupId​

The id of the group where this user belongs.

healthcarePartyId​

The id of the HealthcareParty associated to this User. If this field is not null, then the patientId and deviceId fields should be null.

info

A User where this field is not null is a Data Owner User.

login​

A username for the User. This field can be used in the log in phase.

mobilePhone​

The mobilePhone of the User. It can be used as username to log in.

name​

A free-text field that contains the name of the User.

passwordHash​

If the current User has a password, this field will contain the character *, otherwise it will be null. This field can be used to create or update the password for the User. When the user is created or updated, if this field contains a clear-text password, the backend will store it hashed and salted.

note

If a User logged in with a long token (i.e. an authentication token with a duration > 5 minutes), they will not be able to create or update their own password or the password of any other user, even if they have the permission to do so.

patientId​

The id of the Patient associated to this User. If this field is not null, then the healthcarePartyId and deviceId fields should be null.

info

A User where this field is not null is a Data Owner User.

systemMetadata​

This field contains internal information about the User. Its properties are:

  • isAdmin is a boolean field that is true if the user is an admin.
  • roles is a set of the ids of all the roles assigned to the user.
  • inheritsRoles is a boolean field that is true if the user has no role set and so inherits the roles from the group configuration.
  • loginIdentifiers is a list of the identifiers that the user can use to log in.
  • verifiedEmail is a boolean field that is true if the email of the user has been verified.
  • verifiedMobilePhone is a boolean field that is true if the mobile phone of the user has been verified.
  • uses2fa is a boolean field that is true if the user has two-factor authentication enabled for login with password.

Any update to this property will be prohibited by the backend. To learn how to update the roles on a user, check this how to.

status​

The status of the User. The values can be Active, Disabled, or Registering. Note that if a User has a Disabled status, it will not be able to log in.