App launch within an EHR system via single sign-on
All single sign-on (SSO) schemes hinge on validating that a user is who they say they are. With Redox Nexus, the 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 Nexus 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:
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
Since launching an app via Redox requires extra security measures, 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.
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.
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.