Security for Scalable Registration, Authentication, and Authorization
2.0.0-ballot - STU2 Ballot United States of America flag

Security for Scalable Registration, Authentication, and Authorization, published by HL7 International / Security. This guide is not an authorized publication; it is the continuous build for version 2.0.0-ballot built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/fhir-udap-security-ig/ and changes regularly. See the Directory of published versions

Home

Official URL: http://hl7.org/fhir/us/udap-security/ImplementationGuide/hl7.fhir.us.udap-security Version: 2.0.0-ballot
Active as of 2024-12-02 Computable Name: UDAPSecurity

This Security FHIR® IG has been established upon the recommendations of ONC’s FHIR at Scale Taskforce (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 TEFCA Facilitated FHIR IG, 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.

Introduction

This implementation guide describes how to extend OAuth 2.0 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 Taskforce’s Security Tiger Team, the security model and UDAP workflows outlined in the Carequality FHIR-Based Exchange IG, and implementation guides incorporating UDAP workflows published by the CARIN Alliance and the Da Vinci Project. This guide is also intended to be compatible and harmonious with client and server use of versions 1 or 2 of the HL7 SMART App Launch IG.

The FAST Security project team is working to identify any potential incompatibilities experienced by servers or client applications that support both this IG and the SMART App Launch IG concurrently. For example, while not an incompatibility per se, JWT-based authentication in version 2 of the SMART IG requires server support for either the RS384 or ES384 signature algorithms, while this IG requires server support for RS256. However, this does not present a compatibility issue because RS256 is permitted as an optional algorithm in the SMART IG, while both RS384 and ES384 are permitted as optional algorithms in this IG. Therefore, using any of these three signature algorithms would be compliant with both IGs. Additionally, the question has been raised as to whether this IG can be used for client registration but not used for subsequent authentication. Though adopters of this IG sometimes colloquially refer to its entire workflow as “Dynamic Client Registration”, authentication consistent with this IG is also core to a compliant implementation and the HL7 UDAP FAST Security workgroup recommends that trust communities adopting this IG require the use of this IG for both client registration and authentication, even when SMART is also used, since omitting the UDAP workflow from the authentication step significantly reduces the security benefits to the community. Implementers are requested to submit feedback regarding any other potential issues they have identified related to the concurrent use of both IGs so these may be addressed and resolved during ballot reconciliation.

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.
  • Tiered OAuth for User Authentication: This page provides detailed guidance for user authentication.
  • General Guidance: This page provides general guidance applicable to multiple authorization and authentication workflows.
  • 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.

Signature Algorithm Identifier Conformance
RS256 Implementers SHALL support this algorithm.
ES256 Implementers SHOULD support this algorithm.
RS384 Implementers MAY support this algorithm.
ES384 Implementers MAY support this algorithm.

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, where the leaf certificate corresponds 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 Section 4.1.6 of RFC 7515.

JWT Claims

All JWTs defined in this guide contain the iss, exp, and jti claims. The value of the jti claim is a nonce string value that uniquely identifies a JWT until the expiration of that JWT, i.e. until the time specified in the exp claim of that JWT has passed. Thus, the issuer of a JWT SHALL NOT reuse the same jti value in a new JWT with the same iss value prior to the expiration of the previous JWT. Implementers who track jti values to detect the replay of received JWTs SHALL allow a jti value to be reused after the expiration of any other previously received JWTs containing the same iss and jti values.

Additional JWT Claim requirements are defined later in this guide.

Trust Community Checklist

This section lists some additional topics to be addressed by trust communities adopting this guide:

  1. Assignment of unique URIs to servers for use in certificates and in the iss and sub claims of signed metadata elements (see Section 2.3).
  2. URI used to identify the community in metadata requests (see Section 2.4).
  3. Assignment of unique URIs to client applications for use in certificates and in the iss and sub claims of software statements (see Section 3.1).
  4. Assignment of unique URIs to organizational requestors for use in a B2B Authorization Extension Object (see organization_id in Section 5.2.1.1).
  5. Allowed values for requestor roles in a B2B Authorization Extension Object (see subject_role in Section 5.2.1.1).
  6. Permitted purposes of use for which data may be requested in a B2B Authorization Extension Object (see purpose_of_use in Section 5.2.1.1).
  7. Consent and authorization policies that may be asserted in a B2B Authorization Extension Object and supporting documentation (see consent_policy and consent_reference in Section 5.2.1.1).
  8. Other community policies or conditions that an actor may need to meet before exchanging data with community participants or with other trust communities. Examples include community legal agreements, certificate policies, policies regarding what claims an actor has the authority to assert, and other community requirements relating to the specific use cases, client types and/or grant types supported by the community.