App launch within an EHR system via single sign-on
Last updated: Nov 6, 2024
IMPLEMENTATION
HEALTH TECH VENDOR
PRODUCT OWNER
All single sign-on (SSO) schemes hinge on validating that a user is who they say they are. Our goal 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.
Redox uses the SSO data model to abstract away, or simplify, authentication strategies like SAML Web Browser Profile and SMART on FHIR®. Learn more about each of these below:
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).
The SSO data model sends an HTTP POST request to an endpoint you've configured in the Redox dashboard. The overall flow looks a little like this:
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.
Things you need to know
Launching an app via Redox requires extra security measures. So, Redox sends SSO requests with a JSON Web Token (JWT) signed using HMAC with SH-256, or HS256 (learn about JWTs). A secret is generated in the Redox dashboard on each SSO configuration. The JWT is sent in the Authorization header as a bearer token. Additionally, the JWT conforms to the OpenID Connect claims (refer to openID Connect claim definitions).
What your app must do:
Validate that the Authorization header JWT coming from Redox is correctly signed using the secret value set in the Redox dashboard.
Validate claims in the Redox JWT:
iss is the Source ID initiating the request.
aud is the SSO Configuration ID receiving the request.
iat must be in the past.
exp must be in the future.
Validate any other app-specific business logic you want to enforce using other claims.
Securely craft a redirect URL, which means that (a) the redirect URL should only be valid to use once and (b) any tokens sent in the redirect URL should have sufficient entropy. Your app owns the security of the sessions.
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. Also note that many EHR systems we’ve worked with don't support single logout.
What Redox does:
Validate the incoming SSO launch request.
In SAML, this means verifying the signature using a provided public key.
In SMART/OpenID Connect, this means verifying that the URLs and id_tokens are signed appropriately and match the configuration in Redox.
Maintain the security of the HMAC secret in the Redox dashboard and ensure it's generated securely.
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 system expects content to be returned, we respond with meta http-equiv=”refresh”, a javascript redirect, and a link to the URL.
Don’t use relative URLs. You don’t know what URL the browser will 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.
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.
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.
FHIR® is a registered trademark of Health Level Seven International (HL7) and is used with the permission of HL7. Use of this trademark does not constitute an endorsement of products/services by HL7®.
