On this page:

11.8Trusted Client Mode


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.

Trusted Client Overview

11.8.1Configuring Trusted Client Mode


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.

Trusted Client Settings

11.8.2Making Trusted Client Requests


When making a client request, the client should include the following headers:

Header Description Required
CDR-TrustedClient-Username 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)
CDR-TrustedClient-Permission 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 [permission name] for permissions that do not accept an argument or [permission name]/[argument] for permissions that require an argument. No
CDR-TrustedClient-DoNotInheritPermissions If this header has a value of true, the request will be executed using only the permissions that have been explicitly granted via the CDR-TrustedClient-Permission header. None of the permissions granted to the user via the security module will be used (i.e. permissions retrieved from the user database). No (if this header is not present, its value is assumed to be `false`

Sample Request

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 Patient/123.

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

11.8.3Automatically Creating Users


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.