Embedded iframe

User Interface iframe with SSO

Health Gorilla provides a quick solution for iframing the Health Gorilla User Interface (UI) and allowing Single Sign-On (SSO) for users.

1. iframe Creation

There are three steps to creating the url needed to embed the Health Gorilla UI as an iframe.

Create a JWT to use in the URL
Build the URL using the JWT assertion and the appropriate redirect url.
Embed the URL in the HTML.

1.1 Create the JWT

The url for the iframe will take an assertion as one of the query parameters. To create the assertion, create a web token using the following claims.

Claim	Value
iss	a facility ID provided by Health Gorilla
aud	In Production Environment: https://www.healthgorilla.com/prauth/login In Sandbox Environment: https://sandbox.healthgorilla.com/prauth/login
sub	The UUID of the user. This is provided to Health Gorilla by the customer and is tracked in both the client's system and in the Health Gorilla system. (See Section 2: Creating SSO Users)
exp	Timestamp of the expiration for the assertion. This should be the created timestamp plus three(3) minutes.
iat	Timestamp when the assertion was created.

The JWT token should contain the following header parameters.

Parameter	Value
typ	JWT

The JWT should be signed with a secret key that Health Gorilla will provide, using HS256 (HMAC using SHA-256) algorithm.

Example JWT:

{
  "iss": "Facility ID provided by Health Gorilla",
  "aud": "https://sandbox.healthgorilla.com/prauth/login",
  "sub": "UUID of User to be signed in",
  "exp": 1624660600,
  "iat": 1621982223
}

1.2 Create URL to embed the iFrame

This section will cover building the URL to be used for opening the Health Gorilla UI in an iFrame.

The Authorization service is accessible only over SSL/TLS at
_Production access - https://www.healthgorilla.com/prauth/login
_Sandbox access - https://sandbox.healthgorilla.com/prauth/login

and accepts HTTPS GET or POST requests.

List of available HTTPS query parameters:

Parameter	Description
Assertion	This is the JWT created in the previous step.
tz-offset	Time zone offset from UTC for the user session in, minutes. This is optional.
redirect_uri	The URL that will be opened upon a successful login (See section __ for more details on redirecting to specific pages inside the Health Gorilla UI).

Example of a finished URL with optional tz-offset parameter:

https://sandbox.healthgorilla.com/prauth/login?assertion=enter_your_assertion_here&tz-offset=180&redirect_uri=https://sandbox.healthgorilla.com/clinicalnetwork#dashboard

Example of a finished URL without optional tz-offset parameter:

https://sandbox.healthgorilla.com/prauth/login?assertion=enter_your_assertion_here&redirect_uri=https://sandbox.healthgorilla.com/clinicalnetwork#dashboard

1.3 Implementing the URL

Testing the URL

The URL created in the previous step can be tested, by opening the URL in a web browser. If the URL is created correctly, the Health Gorilla User Interface will open and the user in the sub of the asssertion will be signed in.

Using the URL

The created URL can be use inside of an application to embed the Health Gorilla UI into the application itself, or used to open a new window with the Health Gorilla UI.

2. Creating SSO Users

Health Gorilla uses the PractitionerRole FHIR endpoint for creating users and managing the associated UUIDs. See User Provisioning for more details.

3. iFrame for Patient Chart

Embed the HG Patient Chart as an iframe. This is compatible with User Interface iFrame with SSO .

The parameter patient_chart is used to restrict users access and navigation to only the patient chart.

{portal_url}/prauth/login?patient_chart=true&assertion=your_assertion_here&redirect_uri=uri_to_patient_chart_here

3.1 Embedded SSO Deep Links

It is possible to deep link into certain sections of the Health Gorilla user interface. Below are examples of redirectURLs that can be used to land the user on specific pages within the UI:

3.1.1 Lab Ordering Page with Patient Context

https://sandbox.healthgorilla.com/clinicalnetwork#new/order/lab&patientIds=<PATIENT_GLOBAL_ID>

User Interface iFrame without SSO

The Health Gorilla User Interface can also be framed without using Single Sign On by framing the Health Gorilla login URL: https://www.healthgorilla.com/login.