# Managing Devices In SanteDB, a security device represents an non-human security identity which is assumed by a device. Security devices in SanteDB are intended to represent physical devices (or nodes) which are accessing the SanteDB server. Devices have a secret (like an application) and may optionally have a public signing key registered with the SanteDB server. ## Device List The device list is accessed using the `Devices` menu item in the security menu. The device list shows a list of all active (non-deleted) devices which are permitted to access the SanteDB iCDR instance. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2FJv7EdNPzPQ37QB1B8HJy%2Fimage.png?alt=media\&token=51d37bdf-9269-4a5f-b13b-245928820124) The actions which are available under this panel are: * Create: Allows administrators to create a new device account * Show Deleted: Allows administrators to view deleted accounts and optionally un-delete them. * Edit: Change the properties of the device account * Delete: Remove the device from the iCDR * Lock / Un-lock: Temporarily suspend the device security credential {% hint style="info" %} When locking or deleting a device account - no users or applications running on that device principal may access the SanteDB iCDR system. {% endhint %} ### Device Self-Enrolment The SanteDB dCDR service onboarding process well self-enrol the dCDR device with the central iCDR server (see: [installing-disconnected-gateway](https://help.santesuite.org/installation/installation-1/deployment/installing-software/disconnected-gateway/installing-disconnected-gateway "mention"), [installing-web-access-gateway](https://help.santesuite.org/installation/installation-1/deployment/installing-software/disconnected-gateway/installing-web-access-gateway "mention")). These enrolments can be disabled from the central iCDR device administration panel. When a dCDR device account is disabled, all synchronization and login activity from the web or disconnected gateway device are restricted. ## Creating a Device To create a new security device click the `Create` button. Administrators may wish to manually create new devices when: * A new HL7v2 trading partner is being setup * An new node-authentication partner account needs to be created (for Client Certificate Mapping) ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2FJCtPa67kkmOVhy2uOILO%2Fimage.png?alt=media\&token=4b7bde13-133b-46fb-9fa2-8a39efeb18ed) The `Name` of the device should be unique within the context of the SanteDB solution which has been deployed. The `Extended Properties` panel is used to capture non-security related information about the device. This information is affixed to `Act` events which | Model Name | The name of the device model (used for inventory and validation). | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | Operating System | Information about the operating system platform and version which the device is running. | | Designated Facility | If the device will be used in a single facility, this is the facility in which the device resides (useful for diagnostics and service) | | Designated Person | If the device is administered by another person, this field may track the official point of contact. | ## Editing Devices When editing a device, administrators will be shown the device security information. The `Core Properties` panel shows the provenance information (last update, creation, etc.) as well as the security ID (UUID for the object) and the name with which the device authenticates itself. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2F6ohY9FGf7WfSDfpHkPjk%2Fimage.png?alt=media\&token=26a0d09c-59a3-47ed-ad09-f01972d8eb5e) {% hint style="info" %} The core properties of a security device cannot be edited once a device is created. It is recommended that administrators delete the device and re-add the device credentials. {% endhint %} ### Security Properties The security properties of the device are used for viewing lockout status, invalid authentication attempts and to change or view the device secret. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2FWHA8Bnjil6ZgQEaDlSYM%2Fimage.png?alt=media\&token=22833b30-bc01-46c4-8610-e028cb6d5aa2) #### Invalid Authentications Whenever a device attempts to authenticate with this account, however uses incorrect credentials, this counter is increased. Invalid authentications can be reset using the `Reset` button on the user interface. This action will reset the invalid authentication attempts to 0. #### Lockout After a configured number of invalid authentication attempts, the device will automatically be locked out for a sliding window of time (the more invalid authentications the longer the lockout period). Additionally, administrators can manually lockout an account using the lock mechanism. A device account's lockout can be reset using the `Unlock` button. #### Device Secret The device secret allows an administrator to set a new device secret. The existing secret for the device is not shown (unless the device is new). Administrators can either `Edit` the secret to a custom value: ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2Fg5PlDQWFpKXZBBvX1kz5%2Fimage.png?alt=media\&token=4ba03138-0794-4bec-a4ed-2eebc1d92590) After which, pressing the `Save` button will commit the change. Alternately the administrator can set the secret to a random value with `Reset`. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2Fd2wJwM4wpc4R4vchbRbz%2Fimage.png?alt=media\&token=1028223c-c33c-4b8f-b89b-812352f0581c) {% hint style="info" %} When using X509 client certificate authentication, the secret of the device account should be X509 thumbprint of the certificate which the device will be presenting to the server. The value of the secret should be the `THUMBPRINT` attribute of the certificate in hexidecimal format in lower case. For example: `a11164321e30c84bd825ab20225421434622c52a` {% endhint %} ## Assigning Policies By default a new device will copy its policies from the `DEVICES` group. After creation policies can be customized using the policies panel. New policies are added by first searching for the policy and then pressing the `+` button. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2FB9V5uFzjfuct49G1jHTV%2Fimage.png?alt=media\&token=dc059ac6-f353-4cc8-9e6e-d272944939ac) By default a device will be assigned the policy with a GRANT permission. You can alter these by clicking the permission type. ![](https://3421852694-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LZ0_pjgTp_kx4hqTZ3a%2Fuploads%2FTVmYMvzGfBZfw5JqcWBU%2Fimage.png?alt=media\&token=d62217f4-242c-4d58-aad8-7a872a2f7e6b) The permission types in SanteDB are: * Grant - The device will be granted access to any action or data carrying the policy * Deny - The device is not permitted to access any action or data carrying the policy. * Elevate - The device is, by default, DENY the request, and the server will send a authentication challenge back to the requestor. Users may be required to provide a reason for override and must provide their password. Policies can be removed from a device by clicking the `Remove` button. When a policy is removed, it means that the device (or any application or using using it) has no specific grant applied to the policy (i.e. if the user is in a group its grant will apply, otherwise the default of DENY is applied). ### Certificate Mapping {% hint style="info" %} This section describes a feature in SanteDB v3.0 {% endhint %} SanteDB 3.0 introduces the ability to map certificates for either authentication or digital signatures to devices, applications or users. * Authentication: Authentication certificates are used when the SanteDB server is running in HTTPS mode which requires client certificates, or operating behind NGINX with the correct HTTP headers passed for client authentication. * Digital Signatures: Digital signatures are used in the generation of SanteDB VRP, JWS payloads, sessions, etc. issued by the device.
Certificates are mapped by selecting a PEM encoded file (a `cer, crt` or `der` file extension) and uploading it. {% hint style="warning" %} Ensure that the uploaded file does not contain the private key. Authentication certificates are identified via thumbprint, and only one security device, application or user may use a single certificate for authentication or digital signature. {% endhint %}