Managing Devices
Last updated
Last updated
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.
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.
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
When locking or deleting a device account - no users or applications running on that device principal may access the SanteDB iCDR system.
The SanteDB dCDR service onboarding process well self-enrol the dCDR device with the central iCDR server (see: Installing Disconnected Gateway, Installing Web Access Gateway).
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.
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)
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.
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.
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.
The security properties of the device are used for viewing lockout status, invalid authentication attempts and to change or view the device secret.
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.
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.
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:
After which, pressing the Save button will commit the change. Alternately the administrator can set the secret to a random value with Reset.
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
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.
By default a device will be assigned the policy with a GRANT permission. You can alter these by clicking the permission type.
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).
This section describes a feature in SanteDB v3.0
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.
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.
