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.

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 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:

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"
          }
        ]
      }
    ]
  }

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.