This page is part of the Security for Scalable Registration, Authentication, and Authorization (v0.1.0: STU 1 Ballot 1) based on FHIR R4. The current version which supercedes this version is 1.0.0. For a full list of available versions, see the Directory of published versions

Business-to-Business

B2B client applications registered to use the authorization code grant SHALL obtain an access token for access to FHIR resources by following the OAuth 2.0 authorization code grant flow described in Section 4.1 of RFC 6749, as extended by the SMART App Launch Framework, and with the additional options and constraints discussed below. 

Client applications registered to use the client credentials grant SHALL obtain an access token for access to FHIR resources by following the OAuth 2.0 client credentials grant flow described in Section 4.4 of RFC 6749, and with the additional options and constraints discussed below. As noted in Section 3, the Requestor is responsible for ensuring that the Requestor’s User, if applicable, is using the app only as authorized by the Requestor.

Obtaining an authorization code

The section does not apply to client applications registered to use the client credentials grant.

Client applications registered to use the authorization code grant SHALL request an authorization code as per section 7.1.1 of the HL7 SMART App Launch Framework, with the following additional constraints. Client applications are NOT REQUIRED to include a launch scope or launch context requirement scope. Client applications and servers MAY optionally support UDAP Tiered OAuth for User Authentication to allow for cross-organizational or third party user authentication.

Servers SHALL handle and respond to authorization code requests as per section 7.1.2 of the HL7 SMART App Launch Framework.

Obtaining an access token

Client applications using the authorization code flow SHALL exchange authorization codes for access tokens as per section 7.1.3 of the HL7 SMART App Launch Framework, with the following additional options and constraints. Client applications using the client credentials flow do not use authorization codes.

Constructing Authentication Token

Client app 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.

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:

Authentication JWT Claims
iss	required	The unique identifying URI client for this client application and client app operator. This URI SHALL match the value of a uniformResourceIdentifier entry in the Subject Alternative Name extension of the client's certificate included in the x5c JWT header.
sub	required	The application's client_id as assigned by the authorization server during the registration process
aud	required	The FHIR authorization server's token endpoint URL
exp	required	Expiration time integer for this authentication JWT, expressed in seconds since the "Epoch" (1970-01-01T00:00:00Z UTC)
iat	required	Issued time integer for this authentication JWT, expressed in seconds since the "Epoch"
jti	required	A nonce string value that uniquely identifies this authentication JWT. This value SHALL NOT be reused by the client app in another authentication JWT before the time specified in the exp claim has passed
extensions	conditional	An array of JSON objects containing the HL7 B2B Authorization Extension Object defined below; required for B2B client apps using the client_credentials flow; omit for client apps using the authorization_code flow

The maximum lifetime for an Authentication Token SHALL be 5 minutes, i.e. the value of exp minus the value of iat SHALL NOT exceed 300 seconds. The Authorization Server MAY ignore any unrecognized claims in the Authentication Token. The Authentication Token SHALL be signed and serialized using the JSON compact serialization method.

B2B Authorization Extension Object

The B2B Authorization Extension Object is used by client apps following the client_credentials flow to provide additional information regarding the context under the request for data is authorized. The client app constructs a JSON object containing the following keys and values and includes this object in the extensions array of the Authentication JWT as the value associated with the key name hl7-b2b.

B2B Authorization Extension Object Key Name: "hl7-b2b"
version	required	String with fixed value: "1"
subject_name	conditional	String containing the human readable name of the human requestor; required when applicable; omit if request was not triggered by human action.
subject_id	conditional	String containing a unique identifier for subject; required if known when the subject_name parameter is present. For US Realm, the value of the string SHALL be the subject's individual National Provider Identifier (NPI); omit for subjects who have not been assigned an NPI.
subject_role	conditional	String containing a code identifying the role of the subject; required if known when the subject_name parameter is present. For US Realm, the value of the string SHALL be a code from the National Uniform Claim Committee (NUCC) Provider Taxonomy.
organization_name	required	String containing the human readable name of the organizational requestor. If a subject is named, the organizational requestor is the organization represented by the subject.
organization_id	required	String containing a unique identifier for the organization. The identifier SHALL be a Uniform Resource Identifier (URI). Trust communities SHALL define the allowed URI scheme(s). If a URL is used, the issuer SHALL include a URL that is resolvable by the receiving party.
purpose_of_use	required	An array of one or more strings, each containing a code identifying a purpose for which the data is being requested. For US Realm, the value of each string SHALL be a code from the HL7 PurposeOfUse value set. Trust communities SHOULD further constrain the allowed values from this value set.
consent_policy	optional	An array of one or more strings, each containing a URI identifiying a privacy consent directive policy or other policy consistent with the value of the purpose_of_use parameter.
consent_reference	conditional	An array of one or more strings, each containing the absolute URL of a FHIR [Consent] or [DocumentReference] resource containing or referencing a privacy consent directive relevant to a purpose identified by the purpose_of_use parameter and the policy or policies identified by the consent_policy parameter. The issuer of this Authorization Extension Object SHALL only include URLs that are resolvable by the receiving party. If a referenced resource does not include the raw document data inline in the resource or as a contained resource, then it SHALL include a URL to the attachment data that is resolvable by the receiving party. Omit if consent_policy is not present.

Submitting a token request

Authorization code grant

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:

Token request parameters
grant_type	required	Fixed value: authorization_code
code	required	The code that the app received from the authorization server
redirect_uri	required	The client application's redirection URI matching the redirect_uri value included in the initial authorization endpoint request
client_assertion_type	required	Fixed value: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	required	The signed Authentication Token JWT
udap	required	Fixed value: 1

Client credentials grant

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:

Token request parameters
grant_type	required	Fixed value: client_credentials
client_assertion_type	required	Fixed value: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	required	The signed Authentication Token JWT
udap	required	Fixed value: 1

Authorization servers 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.

For all successful token requests, the Authorization Server SHALL issue access tokens with a lifetime no longer than 60 minutes.