Questions and Answers > Redox SSO – Under The Hood
Questions and Answers

Redox SSO – Under The Hood

The Redox Single Sign-on data model abstracts away vendor SSO authentication strategies, such as the SAML Web Browser Profile and SMART on FHIR (beta).

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 to launch your application.

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.

Below is an example of the structure Redox will use as the body of the JSON web token. You can see a description of the included fields here. Redox uses HMAC SHA256 as the hash algorithm. The token will be sent in the Authorization header as a bearer token. Authorization: Bearer <token>

   "iss": "7ce6f387-c33c-417d-8682-81e83628cbd9",
   "sub": "",
   "aud": "af394f14-b34a-464f-8d24-895f370af4c9",
   "exp": 1597338042,
   "iat": 1597337142,
   "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"

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 (created by Auth0) for testing and debugging JWTs.

The HTTP request

The Redox SSO Data Model will send an HTTP POST request to an endpoint you have configured in the dashboard.

You should:

  1. Verify the JSON Web Token (JWT) signature using the secret also set up in your endpoint
  2. Verify that the token is not expired (normally each SSO request will be a new token)
  3. Respond to the HTTP POSTwith a 302 response and the Location header set to a unique sign-in URL for your application

The overall flow will look like this:

Creating a session on redirect

Since the SSO request is proxied through Redox, it is impossible for the 302 response above to set cookies. Instead, you will need to pass the session information along in the URL. In order to do this securely we recommend using a one-time use token.

Shared Security

Redox will vouch that the SSO request coming to your application are indeed valid, authenticated users. Your application needs to handle a few other security details:

  1. Validate the token as described above
  2. Establish a user session via the redirect method described above
    1. It may be helpful to review the OWASP Session Cheat Sheet
    2. Your application owns the security of the sessions
  3. Expire the sessions as appropriate.
    1. The JWT will provide an expiration time, but this may need to be shortened based on your application policies
    2. Many EHR vendors we’ve worked with do not support single logout.

Best Practices

  1. When you send a 302 to Redox, we’ll return whatever the particular EHR needs – if they can handle redirects we’ll pass it along, if not we’ll find a way to do it. For example in the EHR expects content to be returned, we respond with `meta http-equiv=”refresh”`, a javascript redirect, and a link to the url.
  2. Don’t use relative URLs. You don’t know what the url the browser will actually be set to when your content is loaded. For example it could be about:blank, or the initial Redox URL. Relative URLs will not redirect to your content in both of those cases.
  3. Set cookies after you redirect. Cookies are attached to the domain that they are set on, so if your content is inserted into a frame with about:blank, and then you redirect to your URL, the cookie will be inaccessible.
  4. Avoid referencing window.parent, or top in javascript. Your application will either be hosted in an iFrame, or in a full-blown browser embedded into whatever platform the EHR runs on. Operating on the assumption that you are top-level is the safest path.