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

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.

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

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/smartconfiguration or .well-known/udap object, as applicable, 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.

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.