Authorization

Ocean Cloud Connect can initiate OAuth2 authorization to the EHR/EMR as a client using the client_credentials grant type.

As part of the initial configuration in Cloud Connect with your system, users are prompted for the following values:

  • FHIR API URL: __
  • Client Id: __
  • Client Secret: __
  • OAuth2 Token URL: __
  • Requested Scopes: __ (default: user/*)

Note that clinic administrators (not Ocean system administrators) are the ones who enter these credentials in their clinic's Cloud Connect web portal.

For a reference implementation for the authorization flow, consider consulting the WELL FHIR API Documentation. It is compatible with this FHIR integration and it supports both of the authorization flows described above.

For general security and access control, note that at least some of these credentials should be clinic-specific, not global to the entire vendor EMR/EHR integration. Otherwise, the same credentials for one clinic on the EMR could be leaked and used to gain access to another clinic via the API.

It is left to the integrated system vendor to decide how best to optimize the provision of client credentials with these considerations in mind.

Requirements

  • The OAuth2 credentials must be parsed in the token handler as part of a standard HTTPS POST form submission. The credentials are not passed as a "basic auth header".
  • The EHR/EMR may use either a hosted or a separate authorization server (e.g., Okta, Auth0 or Azure), as long as the authorization server adheres to OAuth2 and provides an access token for the FHIR API. A third-party authorization server is commonly used but is not required or specifically recommended. Vendors are free to use the same server for the authorization, the FHIR resources, and/or the core EMR/EHR, depending on their implementation preference.
  • The clinic's administrators must be able to configure Cloud Connect, including authorization, without the direct involvement of the Ocean IT team. The credentials must be made available to clinic administrators either via a secure portal hosted by the EMR/EHR vendor or with the technical support of the EMR/EHR vendor.
  • The access_token must be long-lasting and/or renewable via the refresh_token. It is unacceptable for clinic administrators to have to manually re-authorize Cloud Connect on a regular basis.
  • Generally, clinic administrators must enter the EHR/EMR's publicly-accessible OAuth2 token request URL as part of the initial authorization.
  • Both the authorization server and the FHIR server must be accessible to Cloud Connect without a firewall blocking its access. If a firewall is necessary, refer to this article for specific information on the allowlist requirements for Ocean.

OAuth2 Scopes Requested by Cloud Connect

Currently the scopes are specified by the user in CC as part of the configuration step. For simplicity, you may want to instruct users to use simple wildcard "catch-all" scopes, like "user/*".

CC also requests "offline_access" as a scope. As with the WELL FHIR API, this scope sometimes serves as a cue for the authorization server to allow CC to request an OAuth2 refresh token.

Depending on the granularity of your scope support, consider supporting the following finer-grained scopes that reflect access permissions assumed by CC when accessing FHIR Resources:

  • user/* OR
  • user/AllergyIntolerance.read
  • user/AllergyIntolerance.write
  • user/Appointment.read
  • user/Appointment.write
  • user/AppointmentResponse.read
  • user/AppointmentResponse.write
  • user/Basic.read
  • user/Basic.write
  • user/Condition.read
  • user/Condition.write
  • user/DiagnosticReport.read
  • user/DiagnosticReport.write
  • user/DocumentReference.read
  • user/DocumentReference.write
  • user/Immunization.read
  • user/MedicationStatement.read
  • user/MedicationStatement.write
  • user/Observation.read
  • user/Observation.write
  • user/Patient.read
  • user/Patient write
  • user/Practitioner.read
  • user/Procedure.read
  • user/Procedure.write
  • user/QuestionnaireResponse.read
  • user/QuestionnaireResponse.write
  • user/Schedule.read
  • user/Schedule.write
  • user/Slot.read
  • user/Slot.write
  • user/Subscription.read
  • user/Subscription.write
  • user/Task.read
  • user/Task.write
  • user/ValueSet.read
  • user/ValueSet.write

For reference, although Ocean's SMART on FHIR launch uses a different OAuth2 context, you may wish to incorporate its scopes as part of your implementation planning. Refer to Ocean's documentation for up-to-date scope definitions for the SMART launch. At a minimum at the time of this writing, the SMART scopes include:

  • launch
  • online_access
  • openid
  • profile
  • fhirUser
  • patient/Patient.read
  • patient/Observation.read
  • user/Practitioner.read

To prevent unexpected issues, ensure that your authorization server does not reject the entire request when it encounters an unknown scope request; ignore it instead.