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.

  1. Create a JWT to use in the URL
  2. Build the URL using the JWT assertion and the appropriate redirect url.
  3. 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.

ClaimValue
issa facility ID provided by Health Gorilla
audIn Production Environment: https://www.healthgorilla.com/prauth/login

In Sandbox Environment:
https://sandbox.healthgorilla.com/prauth/login
subThe 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)
expTimestamp of the expiration for the assertion. This should be the created timestamp plus three(3) minutes.
iatTimestamp when the assertion was created.

The JWT token should contain the following header parameters.

ParameterValue
typJWT

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:

ParameterDescription
AssertionThis is the JWT created in the previous step.
tz-offsetTime zone offset for the user session in, minutes. This is optional.
redirect_uriThe 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:

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

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 PractitionerRole for more details. An Example JSON for creating a provider, with the SSO UUID, can be found below.

{
    "resourceType": "PractitionerRole",
    "contained": [
      {
        "resourceType": "Practitioner",
        "id": "1",
        "meta": {
          "lastUpdated": "2021-07-28T12:33:05.136+03:00",
          "profile": [
            "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner",
            "https://healthgorilla.com/fhir/StructureDefinition/hg-practitioner"
          ]
        },
        "extension": [
          {
            "url": "https://www.healthgorilla.com/fhir/3.0/StructureDefinition/hg-practitioner-login",
            "valueString": "USER LOGIN"
          },
          {
            "url": "https://www.healthgorilla.com/fhir/StructureDefinition/hg-practitioner-password",
            "valueString": "USER PASSWORD"
          },
          {
            "url": "https://www.healthgorilla.com/fhir/3.0/StructureDefinition/hg-practitioner-sso-identifier",
            "valueString": "UUID"
          }
        ],
        "identifier": [
          {
            "system": "http://hl7.org/fhir/sid/us-npi",
            "value": "PROVIDER NPI"
          }
        ],
        "active": true,
        "name": [
          {
            "use": "official",
            "text": "Mike Grands, MS",
            "family": "Grands",
            "given": [
              "Mike",
              "D"
            ],
            "suffix": [
              "MS"
            ]
          }
        ],
        "telecom": [
          {
            "system": "email",
            "value": "[email protected]",
            "use": "work"
          }
        ]
      }
    ],
    "active": true,
    "practitioner": {
      "reference": "#1"
    },
    "organization": {
      "reference": "Organization/HG ORGANZATION ID(can be given to you by Health Gorilla)",
      "display": "Dr. House Practice"
    },
    "code": [
      {
        "coding": [
          {
            "system": "https://www.healthgorilla.com/administrative-role",
            "code": "provider",
            "display": "Provider"
          },
          {
            "system": "http://hl7.org/fhir/practitioner-role",
            "code": "doctor",
            "display": "Doctor"
          }
        ]
      }
    ]
  }

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.

https://sandbox.healthgorilla.com/prauth/login?patient_chart=true&redirect_uri=uri_to_patient_chart_here&assertion=your_assertion_here

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.