When receiving an incoming client request (e.g. a FHIR Patient read), it is commonly desirable to have some sort of authentication and authorization configured on an endpoint in order to ensure that appropriate permissions are enforced, audit log entries are created, etc.
In the general design, credentials received by Smile CDR correspond to an individual user making a request, and they consist of a secret that only that individual user would have (e.g. a password or an OAuth2 bearer token issued to the individual user).
In many architectures, the client calling Smile CDR is not an end user system but instead a server that forms part of a larger system. In this type of architecture, it is generally not useful for Smile CDR to authenticate incoming requests against a user's credentials since they are unavailable to the server. To address these scenarios, endpoints can be configured with Trusted Client Mode enabled, meaning the client is allowed to assert the identity of the end user. Note that in this context, "client" refers to the system that is making HTTP requests to Smile CDR – and this client will often be another server.
This mode should be enabled with caution since it would allow a malicious client to impersonate any user.
Enabling trusted client mode is as simple as setting the appropriate flag in the endpoint module configuration. Additionally, the Assert Permissions property can be enabled to allow clients to assert specific permissions that should be assigned to a user.
When making a client request, the client should include the following headers:
||This header contains the username whose authority will be used to execute the request. Only one header should be present with this name (if multiple headers with this name are present, only the first header will be used).||Yes (if this header is not present, trusted client mode will not be used for the request)|
This header may be repeated 0..* times. Each instance of this header identifies a specific permission that should be added to the authorities being used to execute the given request. The format is simply either
If this header has a value of
||No (if this header is not present, its value is assumed to be `false`|
The following example shows a sample request made by a trusted client on behalf of a user named
hector. It grants permission to read any data in the Patient compartment
GET /Observation?subject=Patient/123&date=2017-01-02 CDR-TrustedClient-Username: hector CDR-TrustedClient-Permission: FHIR_READ_ALL_IN_COMPARTMENT/Patient/123 Accept: application/fhir+json
When the endpoint is configured to use a Local Inbound Security module as its backing authentication store, any trusted client requests will look for pre-existing users in the database.
In some scenarios, it may be useful to have the security module automatically create any users that are referred to by the
CDR-TrustedClient-Username header if they do not already exist.
In the Local Inbound Security module configuration, the Create Unknown Users property can be set to
true to enable this behaviour.