Security for Scalable Registration, Authentication, and Authorization, published by HL7 International - Security WG. 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
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.
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.
This Guide is divided into several pages which are listed at the top of each page in the menu bar.
The requirements in this section are applicable to both consumer-facing and B2B apps and the servers that support them.
All JSON Web Tokens (JWTs) defined in this guide:
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. |
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. |
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.
This section lists some additional topics to be addressed by trust communities adopting this guide:
iss
and sub
claims of signed metadata elements (see Section 2.3).iss
and sub
claims of software statements (see Section 3.1).organization_id
in Section 5.2.1.1).subject_role
in Section 5.2.1.1).purpose_of_use
in Section 5.2.1.1).consent_policy
and consent_reference
in Section 5.2.1.1).