Security for Scalable Registration, Authentication, and Authorization
2.0.0 - STU 2 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 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 Requirements

Page standards status: Informative

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

JSON Web Token (JWT) Requirements

Both the producers and consumers of JWTs specified in this guide SHALL conform to the requirements of [RFC 7515] and the additional requirements below.

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 as defined in [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 elsewhere in this guide.

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.2.1
code_challenge required PKCE code challenge, as discussed further in Section 7.2.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.

Certifications for client applications

As discussed in UDAP Certifications and Endorsements for Client Applications, certifications can be used by client applications or third parties to declare additional information about a client application at the time of registration.

The table in Section 7.4.1 provides a template for UDAP Certification definitions. A trust community MAY publish one or more Certification definitions using this template. A Certification definition specifies the values to be used for the certification_name and certification_uris keys and the allowed grant_types. The trust community determines whether or not the optional scopes and extensions keys will be included in their Certification definition, any restrictions on their allowed values, and whether these keys will be optional, required, or conditionally included when generating a certification. If the extensions keys are used, the Certification definition specifies the additional extensions keys to be included in the extensions object, as discussed in section 7.4.2.

The trust community also determines who will sign the certification, e.g. the app operator or another party. For example, a certification self-signed by a client app operator can be used to declare the intended use of the application within a trust community, while certifications signed by another 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. Note that a trust community could use such a certification to communicate the exchange purposes for which a particular client application operator has been approved.

Using a Certification definition provided by the trust community, a client application or third party MAY generate a certification by constructing a signed JWT conforming to requirements of the certification definition and this section. The certification SHALL contain the required header elements specified in [Section 7.1.3] of this guide and the JWT claims listed in the certification definition. The certification SHALL be signed by the client application operator or by a third party, as specified in the certification definition, 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 signer’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.

Certification template

Template for 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 7.1.4 for additional requirements regarding reuse of values.
certification_name required string with fixed value defined by the trust community, e.g. "Example HL7 Client App Certification"
certification_uris required array of one or more string with fixed values defined by the trust community, e.g.
["http://community.example.com/certifications/example-certifications"].
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 optional String containing a space delimited list of scopes that may be requested by the client application 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: certifications for apps requesting the "client_credentials" grant type SHOULD lisst system scopes; certifications for apps requesting the "authorization_code" grant type SHOULD list user or patient scopes.
extensions optional A JSON object containing one or more certification extension keys, as discussed in the following section.

Certification extension keys example

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 JSON type of the corresponding value, and the conditions under which the key is present, including whether the use of the key is optional, required, etc. The value of each extension key SHALL be a JSON value or a JSON object. For example, a Certification definition could specify that the value of a key is a number, an array of strings, or a FHIR Questionnaire resource, as appropriate for its intended use.

Two non-normative examples of extension keys that could be considered for inclusion in a Certification are presented in the table below:

Example Client Application Certification JWT Extensions Keys
example_exchange_purposes Array of strings, each containing a URI identifying an exchange purpose recognized by the trust community.
example_privacy_disclosures A JSON object containing a set of privacy-related keys and acceptable values established by the trust community.
For example:
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.
Note: This example extension key is derived from an example Certification previously published by Carequality, which can be viewed here.

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.