Handling app launch (SSO) from EHR systems

All single sign-on (SSO) methods are designed to validate a user’s identity, but this can get complicated. Our goal is to simplify all the moving pieces and roles to just two: You and Redox. We verify that the SSO request is valid, and you send us the data to launch your app from an EHR system.

App launch is a process that allows a clinician to open your app from within their EHR system without needing to log in a second time. So they only have to log in a single time to access both systems.

Why is that important? Clinicians work inside the EHR all day. By launching your app directly from their workflow, you provide a seamless, secure, and context-aware experience. For example, a doctor viewing a patient's chart can launch your app, and your app will already know which doctor and patient are active.

Redox simplifies this complex process by normalizing different EHR authentication standards (like SMART on FHIR® and SAML) into a single, easy-to-use data model. Review the SSO data model schema and learn more about these authentication standards:

• SAML Web Browser Profile
• SMART on FHIR®

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

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.

1. A clinician working in the EHR system clicks a button to open your app.
2. Redox receives the request and normalizes it to our SSO data model.
3. Redox sends the normalized HTTP POST request to the app. You should have a configured destination in your Redox organization to receive SSO requests.
4. Your app verifies the request (i.e., checks the Redox JWT).
5. Your app generates a redirect URL to open a new session and sends to Redox.
6. Redox sends the response with the redirect URL to the EHR system.
7. The clinician is redirected to a new session within the app.

See a technical visual of this 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 token.

Launching an app within an EHR system requires extra security measures by Redox and your app.

Redox sends SSO requests with a 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.

Both Redox and your app have parts in validating the handshake. Let’s break down what that looks like:

1. Redox validates the SSO request from the EHR system.
   1. In SAML, this means verifying the signature using a provided public key.
   2. In SMART/OpenID Connect, this means verifying that the URLs and id_tokens are signed appropriately and match the configuration in Redox.
2. Redox maintains the security of the HMAC secret and ensures it’s generated securely.
3. Your app validates the Authorization header JWT from Redox. Make sure it’s correctly signed using the secret value set in the Redox dashboard.
4. Your app validates 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.
5. Your app validates any other business logic you want to enforce using other claims.
6. Your app securely crafts a redirect URL to redirect the user to your app. See redirect best practices below this section.
7. Your app expires the sessions as appropriate. The JWT provides an expiration time, but you might want to shorten that time based on your organization’s security policy. Keep in mind that many EHR systems we’ve worked with don’t support single logout.

• The redirect URL should only be valid to use once.
• Any tokens sent in the redirect URL should have sufficient entropy. Your app owns the security of the sessions.
• 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. 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.
• If working with iframes, your Content-Security-Policy may need to be modified. Since each EHR system and healthcare organization have their own unique domains, you might need to add the domain to allow the embedded login. Sometimes the URL could be specific to the EHR system (e.g., https://...epic.com) or healthcare organization (e.g., https://...amplifymd.com). Check the EHR system’s and healthcare organization’s documentation to find out what you might need to modify so the redirect in an iframe works.