Security for Scalable Registration, Authentication, and Authorization
0.1.0 - STU 1 Ballot

This page is part of the Security for Scalable Registration, Authentication, and Authorization (v0.1.0: STU 1 Ballot 1) based on FHIR R4. The current version which supercedes this version is 1.0.0. For a full list of available versions, see the Directory of published versions

Home

This Security FHIR IG has been established upon the recommendations of ONC’s FHIR at Scale Task Force (FAST) Security Tiger Team, and has been adapted from IGs previously published by UDAP.org. The workflows defined in the Unified Data Access Profiles (UDAP) have been used in several FHIR IGs, including the Carequality FHIR IG, Carin BB IG, DaVinci HREX IG, and others. The objective of this IG is to harmonize workflows for both consumer-facing and B2B applications to facilitate cross-organizational and cross-network interoperability.

Additional enhancements include a formal definition for a B2B Authorization Extension Object to facilitate these transactions.

About This Guide

This implementation guide describes how to extend OAuth 2.0 and the HL7 SMART App Launch Framework using UDAP workflows for both consumer-facing apps that implement the authorization code flow, and business-to-business (B2B) apps that implement the client credentials flow or authorization code flow. This guide covers automating the client application registration process and increasing security using asymmetric cryptographic keys bound to digital certificates to authenticate ecosystem participants. This guide also provides a grammar for communicating metadata critical to healthcare information exchange.

The requirements described in this guide are intended to align with the proposed solutions of the ONC FHIR at Scale Task Force’s Security Tiger Team, the security model and UDAP workflows outlined in the Carequality FHIR-Based Exchange IG, and implementation guide incorporating UDAP workflows published by the CARIN Alliance and the Da Vinci Project. This guide is also intended to be fully compatible with client and server use of the HL7 SMART App Launch Framework v1.0.0.

This Guide is divided into several pages which are listed at the top of each page in the menu bar.

  • Home: The home page provides the introduction and background for this project, and general requirements that apply to all workflows described in this guide.
  • Discovery: This page describes how clients can discover server support for the workflows described in this guide.
  • Registration: This page describes workflows for dynamic registration of client applications.
  • Consumer-Facing: This page provides detailed guidance for authorization and authentication of consumer-facing apps.
  • Business-to-Business: This page provides detailed guidance for authorization and authentication of B2B apps.
  • User Authentication: This page provides detailed guidance for user authentication.
  • FHIR Artifacts: This page provides additional conformance artifacts for FHIR resources.

JSON Web Token (JWT) Requirements

The requirements in this section are applicable to both consumer-facing and B2B apps and the servers that support them.

General requirements and serialization

All JSON Web Tokens (JWTs) defined in this guide:

  1. SHALL conform to the mandatory requirements of RFC 7519.
  2. SHALL be JSON Web Signatures conforming to the mandatory requirements of RFC 7515.
  3. SHALL be serialized using JWS Compact Serialization as per Section 7.1 of RFC 7515.

Signature algorithm identifiers

Signature algorithm identifiers used in this guide are defined in Section 3.1 of RFC 7518. Implementations supporting the UDAP workflows defined in this guide SHALL support RS256. In addition to the algorithm required by the referenced UDAP specifications, this guide also permits the use of ES256 and ES384. Implementations SHOULD support ES256, and MAY support ES384.

JWT headers

All JWTs defined in this guide SHALL contain a Javascript Object Signing and Encryption (JOSE) header as defined in Section 4 of RFC 7515 that conforms to the following requirements:

JWT Header Values
alg required A string identifying the signature algorithm used to sign the JWT. For example:
"RS256"
x5c required An array of one or more strings containing the X.509 certificate or certificate chain, with the leaf certificate corresponding to the key used to digitally sign the JWT. Each string in the array is the base64-encoded DER representation of the corresponding certificate, with the leaf certificate appearing as the first (or only) element of the array.
See https://tools.ietf.org/html/rfc7515#section-4.1.6