Table of Contents

SSO

Single Sign-on (SSO) allows applications on the Redox network to securely connect to other applications and share the login context for a user. The most common use case is a provider in an EHR launching an integrated application, and being automatically logged in, as well as passing context such as which patient and visit are open.

The Redox Single Sign-on data model abstracts away various vendor authentication strategies, such as the SAML Web Browser Profile, but we will support any browser-based SSO scheme an EHR uses as long as it meets our bar for security.

Check out SSO Through Redox - Under the Hood for more information.

How Redox Sits in between you and SSO

All single sign-on schemes hinge on validating that a user is who they say they are.

The goal of Redox SSO is to simplify all the moving pieces and roles to just two: you and Redox. You trust us to verify that the SSO request is valid, and we normalize and pull as much information as possible to pass along.

JSON Web Tokens

The SSO data model uses JSON Web Tokens (JWT) to convey who the user is. The basis for the structure of our tokens is the OpenID ID Token.

When setting up SSO, Redox will generate a shared secret that we sign our token with. You are responsible for validating the signature using this shared secret, along with fields in the token itself (for example, the expiration).

We recommend the useful tools and documentation at jwt.io (created by Auth0) for testing and debugging JWTs.

JSON Web TokenBETAlink

This is body of the JSON web token. Redox will use HMAC SHA256 as the hash algorithm.

The token will be sent in the Authorization header as a bearer token. Authorization: Bearer <token>

Fields

  • iss
    • iss

      String

      Reliable
      Required

      Issuer. This will be the source responsible for the assertion.

  • sub
    • sub

      String

      Reliable
      Required

      Subject Identifier. A locally unique and never reassigned identifier for the End-User, which is intended to be consumed by the Client.
      The sub value is a case sensitive string.

  • aud
    • aud

      String

      Reliable
      Required

      Audience(s) that this token is intended for. This will be your SSO destination.

  • exp
    • exp

      Number

      Reliable
      Required

      Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
      Typically we send date/times in ISO 8601 but this is sent as an epoch to stay compatible with JWT.

  • iat
    • iat

      Number

      Reliable
      Required

      Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
      Typically we send date/times in ISO 8601 but this is sent as an epoch to stay compatible with JWT.

  • name
    • name

      String

      Probable

      End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.

  • given_name
    • given_name

      String

      Probable

      Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

  • family_name
    • family_name

      String

      Probable

      Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

  • middle_name
    • middle_name

      String

      Probable

      Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

  • email
    • email

      String

      Probable

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. This field is not guaranteed to be unique.

  • npi
    • npi

      String

      Probable

      End-User's NPI number. Note that not all providers will have an NPI number.

  • zoneinfo
    • zoneinfo

      String

      Probable

      String from IANA time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles.

  • locale
    • locale

      String

      Probable

      End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties MAY choose to accept this locale syntax as well.

  • phone_number
    • phone_number

      String

      Probable

      End-User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.

  • patient_ids
    • patient_ids[]

      Array

      Probable

      An array of identifiers for the patient.
      Not all SSO sessions will have a Patient context attached.

    • patient_ids[].id

      String

      Probable

      The identifier.

    • patient_ids[].id_type

      String

      Probable

      The type of the indentifier.
      For example, MRN.

  • visit_id
    • visit_id

      String

      Probable

      An indentifier indicating the current visit that the SSO context is happening in.

  • facility_id
    • facility_id

      String

      Probable

      The facility that the user is currently logged in to.
      Facility represents different physical locations of a health system, for example Main Hospital vs. Diabetes Clinic.

  • department_id
    • department_id

      String

      Probable

      The department where the user is currently logged in.
      A facility can contain multiple departments. For example, a hospital may have a physical therapy department and a radiology department.

Sample MessageDownload JSON Schema BETA
{
   "iss": "7ce6f387-c33c-417d-8682-81e83628cbd9",
   "sub": "https://healtsystem.com/provider/4356789876",
   "aud": "af394f14-b34a-464f-8d24-895f370af4c9",
   "exp": 1524021387,
   "iat": 1524020487,
   "name": "Pat Granite MD",
   "given_name": "Pat",
   "family_name": "Granite",
   "middle_name": null,
   "email": null,
   "npi": "4356789876",
   "zoneinfo": "America/Chicago",
   "locale": "en-US",
   "phone_number": "+16085551234",
   "patient_ids": [
      {
         "id": "0000000001",
         "id_type": "MR"
      },
      {
         "id": "e167267c-16c9-4fe3-96ae-9cff5703e90a",
         "id_type": "EHRID"
      },
      {
         "id": "a1d4ee8aba494ca",
         "id_type": "NIST"
      }
   ],
   "visit_id": null,
   "facility_id": "RES General Hospital",
   "department_id": "3N"
}

Sign-onBETAlink

This information is sent in the body of the POST request. It provides a mapping between existing Redox sources and destinations, as well as the claims in the JSON web token in a Redox Data Model Format.

Fields

  • Meta
    • Meta.DataModel

      String

      Reliable
      Required

      Data model.
      E.g. Scheduling, Results

    • Meta.EventType

      String

      Reliable
      Required

      Type of event.
      E.g. New, Update

    • Meta.Test

      Boolean

      Reliable

      Flag as a test message

    • Meta.Source

      String

      Reliable

      Where the message originated.
      Included in messages from Redox

    • Meta.Source.ID

      String

      Reliable

      ID of the source.
      UUID

    • Meta.Source.Name

      String

      Reliable

      Name of the source

    • Meta.Destinations[]

      Array of Objects

      Reliable

      List of destinations to send your message to. All messages must have at least one destination. Queries accept only one destination.
      Required when sending data to Redox

    • Meta.Destinations[].ID

      String

      Reliable

      ID of the destination.
      UUID

    • Meta.Destinations[].Name

      String

      Reliable

      Name of the destination

  • Subject
    • Subject

      String

      Reliable
      Required

      Subject Identifier. A locally unique and never reassigned identifier for the End-User, which is intended to be consumed by the Client.
      The Subject value is a case sensitive string.

  • Expiration
    • Expiration

      Number

      Reliable
      Required

      Expiration time on or after which the ID Token MUST NOT be accepted for processing. The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
      Typically we send date/times in ISO 8601 but this is sent as an epoch to stay compatible with JWT.

  • IssuedAt
    • IssuedAt

      Number

      Reliable
      Required

      Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.
      Typically we send date/times in ISO 8601 but this is sent as an epoch to stay compatible with JWT.

  • Name
    • Name

      String

      Probable

      End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences.

  • FirstName
    • FirstName

      String

      Probable

      Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

  • LastName
    • LastName

      String

      Probable

      Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

  • MiddleName
    • MiddleName

      String

      Probable

      Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used.

  • EmailAddress
    • EmailAddress

      String

      Probable

      End-User's preferred e-mail address. Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. This field is not guaranteed to be unique.

  • NPI
    • NPI

      String

      Probable

      End-User's NPI number. Note that not all providers will have an NPI number.

  • TimeZone
    • TimeZone

      String

      Probable

      String from IANA time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles.

  • Locale
    • Locale

      String

      Probable

      End-User's locale, represented as a BCP47 [RFC5646] language tag. This is typically an ISO 639-1 Alpha-2 [ISO639‑1] language code in lowercase and an ISO 3166-1 Alpha-2 [ISO3166‑1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US; Relying Parties MAY choose to accept this locale syntax as well.

  • PhoneNumber
    • PhoneNumber.Office

      String

      Probable

      End-User's preferred telephone number. E.164 [E.164] is RECOMMENDED as the format of this Claim, for example, +1 (425) 555-1212 or +56 (2) 687 2400. If the phone number contains an extension, it is RECOMMENDED that the extension be represented using the RFC 3966 [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678.

  • Patient
    • Patient.Identifiers[]

      Array

      Probable

      An array of identifiers for the patient.
      Not all SSO sessions will have a Patient context attached.

    • Patient.Identifiers[].ID

      String

      Probable

      The identifier.

    • Patient.Identifiers[].IDType

      String

      Probable

      The type of the indentifier.
      For example, MRN.

  • Visit
    • Visit.VisitNumber

      String

      Reliable

      Number for the visit

    • Visit.Location

      Object

      Probable

      Location of the visit.

    • Visit.Location.Type

      String

      Probable

      Type of location.
      Examples: Clinic, Department, Home, Nursing Unit, Provider's Office, Phone

    • Visit.Location.Facility

      String

      Probable

      Facility.
      Example: Community Hospital

    • Visit.Location.Department

      String

      Probable

      Department

    • Visit.Location.Room

      String

      Probable

      Room.
      Example: 136

Sample MessageDownload JSON Schema BETA
{
   "Meta": {
      "DataModel": "SSO",
      "EventType": "Sign-on",
      "EventDateTime": "2017-11-02T20:37:41.634Z",
      "Test": true,
      "Source": {
         "ID": "7ce6f387-c33c-417d-8682-81e83628cbd9",
         "Name": "Redox Dev Tools"
      },
      "Destinations": [
         {
            "ID": "af394f14-b34a-464f-8d24-895f370af4c9",
            "Name": "Redox EMR"
         }
      ]
   },
   "Subject": "https://healtsystem.com/provider/4356789876",
   "Expiration": "2018-04-18T03:16:27.134Z",
   "IssuedAt": "2018-04-18T03:01:27.134Z",
   "Name": "Pat Granite MD",
   "FirstName": "Pat",
   "LastName": "Granite",
   "MiddleName": null,
   "EmailAddress": null,
   "NPI": "4356789876",
   "TimeZone": "America/Chicago",
   "Locale": "en-US",
   "PhoneNumber": {
      "Office": "+16085551234"
   },
   "Patient": {
      "Identifiers": [
         {
            "ID": "0000000001",
            "IDType": "MR"
         },
         {
            "ID": "e167267c-16c9-4fe3-96ae-9cff5703e90a",
            "IDType": "EHRID"
         },
         {
            "ID": "a1d4ee8aba494ca",
            "IDType": "NIST"
         }
      ]
   },
   "Visit": {
      "VisitNumber": null,
      "Location": {
         "Type": "Inpatient",
         "Facility": "RES General Hospital",
         "Department": "3N",
         "Room": "136"
      }
   }
}