Unattributed Code Systems

Copyright Fragment

This fragment is available on about.html

Copyright and Registered Trademark Uses

• IG © 2021+ HL7 International / Security and UDAP.org. Package hl7.fhir.us.udap-security#2.0.0-ballot based on FHIR 4.0.1. Generated 2025-03-18 Links: Table of Contents | QA Report | Version History | CC0 | Propose a change ( src )
• hl7.fhir.us.hai: Healthcare Associated Infection Implementation Guide ®© HL7 | CC0 ( src )
• HL7®, FHIR®, the HL7® logo, and the FHIR® flame design are registered trademarks of Health Level Seven International. UDAP™ and the gear design are trademarks of UDAP.org. ( src )
• 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 ( src )
• 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. ( src )

External References

Type	Reference	Content
web	www.udap.org
web	github.com	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
web	www.iso.org	ISO maintains the copyright on the country codes, and controls its use carefully. For further details see the ISO 3166 web page: https://www.iso.org/iso-3166-country-codes.html Show Usage ISO 3166-1 Codes for the representation of names of countries and their subdivisions — Part 1: Country code : UDAPSecurity
web	www.udap.org	IG © 2021+ HL7 International / Security and UDAP.org . Package hl7.fhir.us.udap-security#2.0.0-ballot based on FHIR 4.0.1 . Generated 2025-03-18 Links: Table of Contents | QA Report | Version History | | Propose a change
web	www.udap.org	Client apps following this guide will have registered to authenticate using a private key rather than a shared client_secret . Thus, the client SHALL use its private key to sign an Authentication Token as described in this section, and include this JWT in the client_assertion parameter of its token request as described in Section 5.1 of UDAP JWT-Based Client Authentication and detailed further in Section 5.2.2 of this guide.
web	www.udap.org	Authentication Tokens submitted by client apps SHALL conform to the general JWT header requirements above and SHALL include the following parameters in the JWT claims defined in Section 4 of UDAP JWT-Based Client Authentication:
web	www.udap.org	Client applications using the authorization code grant and authenticating with a private key and Authentication Token as per Section 5.2.1 SHALL submit a POST request to the Authorization Server’s token endpoint containing the following parameters as per Section 5.1 of UDAP JWT-Based Client Authentication. Client apps authenticating in this manner SHALL NOT include an HTTP Authorization header or client secret in its token endpoint request. The token request SHALL include the following parameters:
web	www.udap.org	Client applications using the client credentials grant and authenticating with a private key and Authentication Token as per Section 5.2.1 SHALL submit a POST request to the Authorization Server’s token endpoint containing the following parameters as per Section 5.2 of UDAP JWT-Based Client Authentication. Client apps authenticating in this manner SHALL NOT include an HTTP Authorization header or client secret in its token endpoint request. The token request SHALL include the following parameters:
web	www.udap.org	An Authorization Server receiving token requests containing Authentication Tokens as above SHALL validate and respond to the request as per Sections 6 and 7 of UDAP JWT-Based Client Authentication.
web	www.udap.org	Client apps following this guide will have registered to authenticate using a private key rather than a shared client_secret . Thus, the client SHALL use its private key to sign an Authentication Token as described in this section, and include this JWT in the client_assertion parameter of its token request as described in Section 5.1 of UDAP JWT-Based Client Authentication and detailed further in Section 4.2.2 of this guide. For clients and servers that also support the SMART App Launch IG, this overrides the requirement for the client to use HTTP Basic Authentication with a client_secret in Section 7.1.3 of the SMART App Launch IG v1.0.0.
web	www.udap.org	Client applications SHALL submit a POST request to the Authorization Server’s token endpoint containing the following parameters as per Section 5.1 of UDAP JWT-Based Client Authentication. Client apps authenticating in this manner SHALL NOT include an HTTP Authorization header or client secret in the token request. The token request SHALL include the following parameters:
web	www.udap.org	The requirements in this section are applicable to both consumer-facing and B2B apps and the servers that support them. The client and the server SHALL conform to the underlying server metadata profile in UDAP Server Metadata .
web	www.udap.org	UDAP metadata SHALL be structured as a JSON object as per section 1 of  UDAP Server Metadata  and discussed further in Section 2.2 .
web	www.udap.org	An Authorization Server MAY include additional metadata elements in its metadata response as described in UDAP Server Metadata . However, a conforming client application might not support additional metadata elements.
web	www.udap.org	The client SHALL validate the signed metadata returned by the server as per Section 3 of UDAP Server Metadata .
web	www.udap.org	A client application or third party MAY construct a certification by constructing a signed JWT as detailed in this section. The certification SHALL contain the required header elements specified in [Section 1.2.3] of this guide and the JWT claims listed in the table below. The certification SHALL be signed by the client application operator or by a third party using the signature algorithm identified in the alg header of the certification and with the private key that corresponds to the public key listed in the client’s X.509 certificate identified in the x5c header of the certification. Recognized Certification JWT claims and server processing rules for Certifications submitted by a client application are detailed in UDAP Certifications and Endorsements for Client Applications . A trust community MAY define additional keys to be included in the extensions object, as demonstrated in the example below.
web	carequality.org	Note: The example keys listed below in the description of the privacy_disclosures extension key are derived from an example Certification previously published by Carequality, which can be viewed here .
web	carequality.org	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 .
web	www.udap.org	Authorization Servers SHALL support dynamic registration as specified in the UDAP Dynamic Client Registration profile with the additional options and constraints defined in this guide. Confidential clients that can secure a secret MAY use this dynamic client registration protocol as discussed further below to obtain a client_id . Other client types SHOULD follow the manual registration processes for each Authorization Server. Future versions of this guide may add support for dynamic client registration by public clients which cannot protect a private key.
web	www.udap.org	To register dynamically, the client application first constructs a software statement as per section 2 of UDAP Dynamic Client Registration.
web	www.udap.org	The Authorization Server SHALL validate the registration request as per Section 4 of UDAP Dynamic Client Registration. This includes validation of the JWT payload and signature, validation of the X.509 certificate chain, and validation of the requested application registration parameters.
web	www.udap.org	If a new registration is successful, the Authorization Server SHALL return a registration response with a 201 Created HTTP response code as per Section 5.1 of UDAP Dynamic Client Registration, including the unique client_id assigned by the Authorization Server to that client app. Since the UDAP Dynamic Client Registration profile specifies that a successful registration response is returned as per Section 3.2.1 of RFC 7591 , the authorization server MAY reject or replace any of the client’s requested metadata values submitted during the registration and substitute them with suitable values.
web	www.udap.org	If a new registration is not successful, e.g. it is rejected by the server for any reason, the Authorization Server SHALL return an error response as per Section 5.2 of UDAP Dynamic Client Registration.
web	www.udap.org	Authorization Servers MAY support the inclusion of certifications and endorsements by client application operators using the certifications framework outlined in  UDAP Certifications and Endorsements for Client Applications . Authorization Servers SHALL ignore unsupported or unrecognized certifications.
web	www.udap.org	Client applications registered to use the authorization code grant MAY utilize the user authentication workflow described in UDAP Tiered OAuth for User Authentication , as profiled below. The UDAP Tiered OAuth workflow allows the client application to include the base URL of a preferred OpenID Connect Identity Provider (IdP) service in the initial request to the data holder’s OAuth authorization endpoint. If Tiered OAuth is supported by the data holder and the data holder trusts the IdP indicated by the client, then the data holder will request that the IdP authenticate the user, and return authentication results and optional identity information directly to the data holder using standard OIDC workflows. Note that the client application does not interact directly with the IdP as part of this workflow.
web	www.udap.org	The client app indicates the preferred Identity Provider to the data holder as per Section 2 of the UDAP Tiered OAuth specification by modifying the authorization endpoint request described in Section 4.1 for consumer-facing apps or Section 5.1 for business-to-business apps as follows:
web	openid.net	The meaning of the extension parameter idp is undefined if udap is absent from the list of requested scopes. The IdP’s base URL is the URL listed in the iss claim of ID tokens issued by the IdP as detailed in Section 2 of the OpenID Connect Core 1.0 specification (OIDC Core).
web	www.udap.org	For the purposes of the interactions between the data holder and the IdP, the data holder takes on the role of client app and the IdP takes on the role of server/data holder and interacts as per Section 3 of UDAP Tiered OAuth , as detailed below.
web	openid.net	If the IdP is trusted by the data holder, and the data holder is registered as a client with the IdP, then the data holder, acting as an OIDC client, SHALL make an authentication request to the IdP’s authorization endpoint as per Section 3.1.2.1 of OIDC Core and Section 3.4 of UDAP Tiered OAuth . The scope query parameter of the authentication request SHALL contain at least the following two values: openid and udap . The IdP SHALL authenticate the user as per Sections 3.1.2.2 - 3.1.2.6 of OIDC Core and Sections 4.1 - 4.2 of UDAP Tiered OAuth .
web	www.udap.org	If the IdP is trusted by the data holder, and the data holder is registered as a client with the IdP, then the data holder, acting as an OIDC client, SHALL make an authentication request to the IdP’s authorization endpoint as per Section 3.1.2.1 of OIDC Core and Section 3.4 of UDAP Tiered OAuth . The scope query parameter of the authentication request SHALL contain at least the following two values: openid and udap . The IdP SHALL authenticate the user as per Sections 3.1.2.2 - 3.1.2.6 of OIDC Core and Sections 4.1 - 4.2 of UDAP Tiered OAuth .
web	openid.net	If the IdP is trusted by the data holder, and the data holder is registered as a client with the IdP, then the data holder, acting as an OIDC client, SHALL make an authentication request to the IdP’s authorization endpoint as per Section 3.1.2.1 of OIDC Core and Section 3.4 of UDAP Tiered OAuth . The scope query parameter of the authentication request SHALL contain at least the following two values: openid and udap . The IdP SHALL authenticate the user as per Sections 3.1.2.2 - 3.1.2.6 of OIDC Core and Sections 4.1 - 4.2 of UDAP Tiered OAuth .
web	www.udap.org	The data holder SHALL validate the state parameter value returned in the response from the IdP. If the IdP does not return a valid state parameter value in its authentication response, the data holder SHALL return a server_error error response to the client app and terminate this workflow as per Section 4.1 of UDAP Tiered OAuth . If the IdP returns an error response with a valid state parameter value, the data holder SHALL return a suitable error response to the client app and terminated this workflow as per Section 4.2 of UDAP Tiered OAuth .
web	openid.net	If the IdP returns a successful authentication response with valid state parameter value and an authorization code, the data holder SHALL exchange the code for an access token and ID Token by making a request to the IdP’s token endpoint as per Section 3.1.3.1 of OIDC Core and Section 4.3 of UDAP Tiered OAuth . For this request, the data holder as client app SHALL utilize the JWT-based authentication process as described in Section 4.2.2 of this guide. ID Tokens issued by the IdP SHALL conform to the requirements of Section 1.2 of this guide and Section 4.3 of UDAP Tiered OAuth .
web	www.udap.org	If the IdP returns a successful authentication response with valid state parameter value and an authorization code, the data holder SHALL exchange the code for an access token and ID Token by making a request to the IdP’s token endpoint as per Section 3.1.3.1 of OIDC Core and Section 4.3 of UDAP Tiered OAuth . For this request, the data holder as client app SHALL utilize the JWT-based authentication process as described in Section 4.2.2 of this guide. ID Tokens issued by the IdP SHALL conform to the requirements of Section 1.2 of this guide and Section 4.3 of UDAP Tiered OAuth .
web	openid.net	If the IdP returns an ID Token, the data holder SHALL then validate the ID Token as per Section 3.1.3.5 of OIDC Core . If the IdP does not return an ID Token, or the ID Token cannot be successfully validated, or an error response is retured by the IdP, the data holder MAY return an invalid_idp error code to the client app or attempt an alternate user authentication as described above.
web	www.udap.org	When an ID Token has been returned and validated, the data holder SHOULD use the ID Token to attempt to match the authenticated user to a user or role in its own system, as appropriate for the resources requested. As discussed in Sections 4.4 and 4.5 of UDAP Tiered OAuth , the iss and sub values of the ID Token can be used together by the data holder to identify a single person over time, i.e. the data holder can attempt to map the pair ( iss , sub ) to a known users in the data holder’s system. If the data holder has previously performed this mapping or has otherwise bound the pair ( iss , sub ) to a local user or role, it MAY rely on this previous mapping for subsequent authentications. If the ID Token does not contain sufficient information to perform the mapping, the data holder MAY attempt to retrieve additional information for the IdP’s UserInfo endpoint as described in Section 5.3 of OIDC Core . In many cases, the information provided by the IdP will allow the data holder to resolve the authenticated user to a single local user or role with high confidence. If necessary, the data holder MAY interact with the user following the redirection from the IdP back to the data holder’s redirection URI to increase confidence in the resolution process. For example, if there is more than one possible match, the data holder may transmit a one-time code to an electronic address of record known to the data holder to confirm a specific match. If the data holder is unable to resolve the authenticated user to a local user or role, as appropriate for the resources requested, it SHALL return an access_denied error response to the client app’s authorization request and terminate the workflow.
web	openid.net	When an ID Token has been returned and validated, the data holder SHOULD use the ID Token to attempt to match the authenticated user to a user or role in its own system, as appropriate for the resources requested. As discussed in Sections 4.4 and 4.5 of UDAP Tiered OAuth , the iss and sub values of the ID Token can be used together by the data holder to identify a single person over time, i.e. the data holder can attempt to map the pair ( iss , sub ) to a known users in the data holder’s system. If the data holder has previously performed this mapping or has otherwise bound the pair ( iss , sub ) to a local user or role, it MAY rely on this previous mapping for subsequent authentications. If the ID Token does not contain sufficient information to perform the mapping, the data holder MAY attempt to retrieve additional information for the IdP’s UserInfo endpoint as described in Section 5.3 of OIDC Core . In many cases, the information provided by the IdP will allow the data holder to resolve the authenticated user to a single local user or role with high confidence. If necessary, the data holder MAY interact with the user following the redirection from the IdP back to the data holder’s redirection URI to increase confidence in the resolution process. For example, if there is more than one possible match, the data holder may transmit a one-time code to an electronic address of record known to the data holder to confirm a specific match. If the data holder is unable to resolve the authenticated user to a local user or role, as appropriate for the resources requested, it SHALL return an access_denied error response to the client app’s authorization request and terminate the workflow.
web	www.udap.org	If the data holder successfully maps the authenticated user to a user or role in its own system, as appropriate for the resources requested, it SHALL also obtain authorization from the user for the scopes requested by the client app, if such authorization is required, as per Section 4.5 of UDAP Tiered OAuth , returning to the workflow defined in Section 4.1 or Section 5.1 of this guide, for consumer-facing or B2B apps, respectively.
web	www.udap.org	Note: These examples are non-normative. Line breaks and indentations have been added for readability and would not be part of an actual request or response. Additional examples can be found in the UDAP Tiered OAuth specification.

Internal Images