SSO for the Data Model API

All single sign-on schemes hinge on validating that a user is who they say they are. The goal of our SSO data model 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.

The Redox Single Sign-on data model abstracts away, or simplifies, authentication strategies like SAML Web Browser Profile and SMART on FHIR®. Learn more about each of these below:

JSON Web Tokens

The SSO data model uses JSON Web Tokens (JWT) to convey who the user is. Learn how to authenticate with JWT.

Learn more about authentication standards

If you want more of a conceptual summary, learn how OAuth works or watch this YouTube tutorial on JWT. Or, if you're familiar with the basics of JWT but you need more of a technical reference, check out this Request for Comments (RFC) on JWT.

And just a tip: JWT is an implementation of SMART backend services authorization, so any tools that conform to SMART backend services should work with this authorization method. Learn more about SMART backend services authorization.

When setting up SSO, we generate a shared secret that we sign our token with. You're responsible for validating the signature using this shared secret, along with fields in the token itself (e.g., the expiration).

Explore testing and debugging tools and documentation for JWT.

The HTTP request

The SSO data model sends an HTTP POST request to an endpoint you've configured in the Redox dashboard. Your responsibilities:

  1. Verify the JWT signature using the secret also set up in your endpoint.
  2. Verify that the token isn't expired (normally each SSO request uses a new token).
  3. Respond to the HTTP POST with a 302 response and the Location header set to a unique sign-in URL for your system.

The overall flow looks a little like this:

SSO data model flow
SSO data model flow

Since the SSO request is proxied through Redox, it's not possible for your 302 response to set cookies. Instead, you must pass the session information in the URL. To do this securely, we recommend using a one-time use token.

Shared security

We share security responsibilities with you for SSO. We ensure that the SSO request coming to your system is from valid, authenticated users, while your system must handle these security details:

  1. Validate the token with the shared secret value.
  2. Establish a user session via the redirect method via the 302 response and URL with session information. Your system owns the security of the sessions. Review the OWASP Session Cheat Sheet for more details.
  3. Expire the sessions as appropriate. Note that the JWT provides an expiration time, but this may need to be shortened based on your system policies. And also note that many EHR systems we’ve worked with don't support single logout.

Best practices

  1. When you send a 302 to Redox, we return whatever the particular EHR system needs; if they can handle redirects we pass it along, but we find a way to do it if they don't. For example, if 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 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. In either of those cases, relative URLs don't redirect to your content.
  3. Set cookies after you redirect. Cookies are attached to the domain that they're set on, so if your content is inserted into a frame with about:blank and then you redirect to your URL, the cookie is inaccessible.
  4. Avoid referencing window.parent, or top in JavaScript. Your system is either hosted in an iFrame or in a full-blown browser embedded into whatever platform the EHR system runs on. The safest path is to assume that you're on the top level.

On this Page