CambioOpenServicesIG - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Security

Regulatory

The information owner of the system is responsible for ensuring that consumption of produced information is only disclosed to approved consumers. Compliance with local regulations must be evaluated when developing applications using the Cambio Open Services (COS) APIs.

Information Security

All communication between client and COS services are encrypted using TLS v1.3 (or higher when available).

Authentication

COS currently supports only the OAuth 2.0 Client Credentials flow. Each integration is provisioned with a client_id and client_secret which can be used to obtain an access token from the COS Identity Provider(IdP). The access token can be used to invoke COS APIs. Invalid or missing credentials yield HTTP 401.

Authorization

Each integration must be configured in COS IdP with relevant access scopes based on which APIs going to be accessed. COS supports SMART on FHIR (v1 and v2) scope notations. Insufficient scope yields HTTP 403.

See more:

• SMART ON FHIR V2 scopes

• SMART ON FHIR V1 scopes

• If the end user is a healthcare professional, it is recommended to use user scopes.
• If the end user is a patient, it is recommended to use patient scopes.
• If the apis are going to be used by a device, or it is a system level integration without end user context, it is recommended to use system scopes.

If the scope is patient, then a filtering(PDA - Patient Data Access) will be applied by COS to ensure that patient is allowed to see the data returned by the COS api.

But if the scope is user or system, no filtering will be applied by COS, and it is expected that the client application will handle any necessary data filtering.

example scopes:

• user/Patient.r
• patient/Observation.s
• system/Observation.c Note: It is possible to combine multiple grants and in that case the cruds order has to be followed (c > r > u > d > s). Ex: user/Observation.cr is valid but user/Patient.rc is not valid.

Intended Use of Client Credentials Flow

This flow is suitable for:

• System to System integration where a trusted backend service calls COS APIs.

Explicitly Avoid

Do not use the Client Credentials flow directly from:

• Browser based applications.
• Native mobile apps
• Desktop apps distributed to end users
• Embedded scripts or IoT devices lacking secure secret storage

Reason: The client_secret cannot be kept confidential in these environments and may be extracted via debugging tools, reverse engineering, or network inspection, leading to unauthorized API access.

Token Handling

• Avoid writing tokens in log files, disks unencrypted
• Do not forward raw COS tokens to end-user clients

Recommended Integration Pattern for Public Apps

Public applications should call a secure backend that:

• Authenticate end users by the App Backend
• Holds and protects the COS client_secret
• Performs token acquisition and caching(when necessary)
• Perform COS API calls on behalf of the end user
• Use least -privilege scopes

Impact on SMART on FHIR Apps

Interactive SMART apps typically rely on Authorization Code flow which performs end-user authentication. Since COS supports only Client Credentials flow, the following limitations are applied:

• User-context authorization is not available
• Will require some mitigation actions which are explained below.

Mitigation Strategies for SMART App Developers

• Implement end user authentication as part of your application backend
• Use the authenticated end user context to enforce access control in your application
• Implement the application backend that mediates all FHIR requests to COS
• Enforce user/session access rules server-side before calling COS
• Maintain an internal authorization model mapping users to permissible COS scopes

Example Architecture - Safe Use of Client Credentials