Security for Scalable Registration, Authentication, and Authorization
2.0.0-ci - STU2 Post-Ballot CI 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-ci 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

General Guidance

This section contains general guidance applicable to multiple authorization and authentication workflows.

Authorization code flow

The constraints in the following subsections apply to all workflows utilizing the authorization code flow. Authorization requests submitted by client applications SHALL include the following parameters:

Authorization request parameters
response_type required Fixed value: code
client_id required The client identifier issued to the client application at registration.
redirect_uri conditional The client application's redirection URI for this session, REQUIRED when the client application registered more than one redirection URI. The value SHALL match one of the redirection URIs registered by the client.
scope required Space-delimited list of requested scopes of access.
state required An opaque value used by the client to maintain state between the request and callback, as discused further in Section 7.1.1
code_challenge required PKCE code challenge, as discussed further in Section 7.1.2
code_challenge_method required Fixed value: S256

The state parameter

A Client application SHALL include the state parameter in its authorization request. An Authorization Server SHALL return an error code of invalid_request as per Section 4.1.2.1 of RFC 6749 if a client application does not include a state value in its authorization request.

Servers SHALL include the state parameter and corresponding value provided by the client application in the authorization response as per RFC 6749. The client application SHALL NOT proceed if the state parameter is not included in the authorization response or its value does not match the value provided by the client application in the corresponding authorization request.

Proof Key for Code Exchange (PKCE)

Client applications and Authorization Servers SHALL utilize Proof Key for Code Exchange (PKCE) with code_challenge_method of S256 as defined in RFC 7636. An Authorization Server SHOULD return an error as per Section 4.4.1 of RFC 7636 if a client application does not include a code_challenge is its authorization request.

The Authorization Server SHALL return an error in response to a token request as per Section 4.6 of RFC 7636 if the client included a code_challenge in its authorization request but did not include the correct code_verfier value in the corresponding token request.

Scope negotiation

The following constraints have been adapted from the TEFCA Faciliated FHIR SOP. Some of the constraints in that SOP conflict with constraints found elsewhere in this IG, or relate to requirements in other IGs such as the SMART App Launch IG. This will need to be resolved prior to STU2 publication. Feedback is requested.

A wildcard scope is a scope that can be alternatively represented as a set of non-wildcard scopes. An example of a wildcard scope is the SMART App Launch v1.0.0 scope patient/Observation.* which can expanded to the set of two non-wildcard scopes: patient/Observation.read and patient/Observation.write. Granting the wildcard scope to a client application is equivalent to granting the corresponding expanded set of non-wildcard scopes.

The constraints enumerated below apply for scope negotiation between client applications and servers. Unless otherwise specified, these constraints apply for both registration requests and access token requests made by client applications, and the corresponding responses returned by servers.

  1. The scopes_supported metadata SHALL be present in the .well-known/udap object and SHALL list all scopes supported including all supported wildcard scopes.

    `scopes_supported` is currently optional in the Discovery section of this guide. References to SMART specific content should be removed.
  2. Client applications and servers MAY support wildcard scopes.
  3. A client application MAY request a wildcard scope only if wildcards are specified in the server’s scopes_supported metadata list.
  4. If a client application requests a wildcard scope and the server supports wildcards, then the server SHOULD return either the wildcard scope or an expanded set of scopes that the client has been granted in its response.
  5. If a client application requests a wildcard scope and the server does not support wildcard scopes, then the server SHOULD respond with an error of “invalid_scope”.

    Note: "invalid_client_metadata" is the corresponding registration request error.
  6. If a server supports OIDC or SMART App Launch scopes, the server SHOULD put the corresponding scopes (e.g. “openid”, “offline_access”, “email”, “fhirUser”, etc.) in their scopes_supported metadata.
  7. A server MAY grant fewer scopes than requested by the client application if the client application cannot have a scope specified in the request based on technical or policy guidelines at the responding organization or if the server does not recognize one or more of the requested scopes.
  8. A server SHOULD respond with “invalid_scope” only if a wildcard scope is requested and not supported, or if none of the requested scopes are supported.

    Note: "invalid_client_metadata" is the corresponding registration request error.
  9. At the time of a token request, an authorization server MAY grant additional scopes that are not in the set of scopes requested by the client application if the application has been registered with the server with a different set of scopes than was requested at registration based on technical or policy guidelines at the responding organization.
  10. The scopes granted by a server to a client application at the time of an access token request MAY be the same as the set from registration or MAY be a subset.
  11. The scopes granted by a server to a client application at the time of an access token request MAY be the same as the set of scopes requested by the client application or MAY be a subset.
  12. An application SHOULD be able to receive a superset of the scopes requested if the server’s policies dictate that a request with a certain system or user/user role is granted specific scopes that are not part of the original request.
  13. A server SHOULD return “invalid_scope” only if none of the scopes requested are available and/or not part of the scopes requested during registration.

    Note: "invalid_client_metadata" is the corresponding registration request error.
  14. A server SHALL include the scope parameter in a token response if the set of scopes granted by the server to the client application is not identical to the set of scopes requested by the client application, or if the client application does not include a set of requested scopes in its request.

Certification example for client applications

This section provides an example UDAP Certification that can be used by client applications or third parties to declare additional information about the client application at the time of registration.

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.

Example Client Application Certification JWT Claims
iss required Issuer of the JWT -- unique identifying URI of the signing entity. This SHALL match the value of a uniformResourceIdentifier entry in the Subject Alternative Name extension of the signer's certificate included in the x5c JWT header and SHALL uniquely identify a single signing entity over time.
sub required Subject of the JWT -- unique identifying client URI. This SHALL match the value of a uniformResourceIdentifier entry in the Subject Alternative Name extension of the client's certificate and SHALL uniquely identify a single client app operator and applications over time. For a self-signed certification, this is same as iss.
aud optional The "registration URL" of the intended Authorization server(s), i.e. the same URL to which the registration request will be posted. If absent, this certification is intended for all Authorization Servers. The value can be a single string or array of strings.
exp required Expiration time integer for this software statement, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC). The exp time SHALL be no more than 3 years after the value of the iat claim.
iat required Issued time integer for this software statement, expressed in seconds since the "Epoch"
jti required A nonce string value that uniquely identifies this software statement. See Section 1.2.4 for additional requirements regarding reuse of values.
certification_name required string with fixed value: "Example HL7 Client App Certification"
certification_uris required array of one string with fixed value: ["URI TBD"]
grant_types required Array of strings, each representing a requested grant type, from the following list: "authorization_code", "refresh_token", "client_credentials". The array SHALL include either "authorization_code" or "client_credentials", but not both. The value "refresh_token" SHALL NOT be present in the array unless "authorization_code" is also present.
response_types conditional Array of strings. If grant_types contains "authorization_code", then this element SHALL have a fixed value of ["code"], and SHALL be omitted otherwise
scope required String containing a space delimited list of scopes that may be requested by the client application for use in subsequent requests. The Authorization Server MAY consider this list when deciding the scopes that it will allow the application to subsequently request. Note for client apps that also support the SMART App Launch framework: apps requesting the "client_credentials" grant type SHOULD request system scopes; apps requesting the "authorization_code" grant type SHOULD request user or patient scopes.
extensions optional A JSON object containing one or more of the keys listed in the following section.

Note: A certification self-signed by a client app operator can be used to declare the intended use of the application within a trust community. Certifications signed by a third party, such as the trust community administrator or an independent accreditor, can be used to assist servers in determining what a client application is authorized to do within a trust community. For example, a trust community administrator could use this certification to communicate the exchange purposes for which a particular client application operator has been approved.

Certification extension keys example

This section lists two example extension keys that could be considered for inclusion in a Certification. When defining a Certification, a trust community MAY define one or more extension keys to be included in the extensions object of the Certification JWT. The value of each extension key SHALL be a JSON value or a JSON object. For example, a Certification definition could specify a number, an array of strings, or a FHIR Questionnaire resource as the value of an extension key.

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.
Example Client Application Certification JWT Extensions Keys
exchange_purpose required Array of strings, each containing a URI identifying an exchange purpose recognized by the trust community.
privacy_disclosures optional A JSON object containing a set of privacy-related keys and acceptable values established by the trust community.
Examples:
1. the key funding could be used to express the app's source of funding.
2. the key data_storage could be used to identify where a patient's data is stored.
3. the key data_access_notification could be used to indicate whether a user is notified when their data is accessed by someone else.

Using this guide with the SMART App Launch framework

Editor's Note: This section is being added per FHIR-49185 and is not yet completed. The SMART note from the intro page and all SMART related comments from the ballot version have been consolidated in this section. Additional specific points mentioned in the ticket are in the process of being added.

This guide is intended to be compatible and harmonious with client and server use of versions 1 or 2 of the HL7 SMART App Launch IG. Although the use of the SMART App Launch framework is not required to be conformant with this guide, this section provides guidance on how the UDAP and SMART App Launch frameworks can be used together successfully.

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. 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 in future updates.

Key Algorithms: 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.

Consistent use of both guides: 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.

Editor's Note: The preceding paragraph may be moved back to section 1 during final editorial review as it is not limited to SMART.

Discovery: Servers conforming to this guide are generally expected, but not required, to also support the HL7 SMART App Launch Framework, which defines additional discovery and metadata requirements.

For servers that also support the SMART App Launch Framework, there is some expected overlap in the UDAP metadata elements defined in Section 2 and metadata that a server may return for other workflows, e.g. OAuth 2.0 authorization and token endpoints are also included in metadata defined in the SMART App Launch Framework. Having different metadata endpoints permits servers to return different metadata values for different workflows. For example, a server could operate a different token endpoint to handle token requests from clients conforming to this guide. Thus, for the workflows defined in this guide, client applications SHALL use the applicable values returned in a server’s UDAP metadata.

Editor's Note: The SHALL requirement in the previous paragraph is duplicative with the text in Section 2 and may be removed during later review.

Note for client apps that also support the SMART App Launch framework: apps requesting the "client_credentials" grant type SHOULD request system scopes; apps requesting the "authorization_code" grant type SHOULD request user or patient scopes.

Authorization Requests: Client applications that also support the SMART App Launch IG are not required to include a launch scope or launch context requirement scope in an authorization request. However, the capability for a client application to request a launch context from the server is useful in many workflows, e.g. consumer facing workflows. Since this IG does not restrict the inclusion of additional parameters in an authorization request or in the corresponding server response, clients are able initiate either the SMART standalone or EHR launch workflows to request a launch context. For example, a client could initiate the SMART standalone launch by including the launch/patient scope in its authorization request to a server that supports this SMART workflow.

Token Requests: For clients and servers that also support the SMART App Launch IG, the requirement to authenticate using a private key in Section 4.2.1 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.

Token Response: Although this guide does not currently constrain the type or format of access tokens, the SMART App Launch framework, when used together with this guide, may limit the allowed access token types (e.g. Bearer) and/or formats (e.g. JWT). Since this IG does not restrict the server from including additional parameters in the token response, servers can include other parameters specified by the SMART App Launch framework for this purpose, e.g. launch context parameters.