Security for Scalable Registration, Authentication, and Authorization
0.1.0 - STU 1 Ballot

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

Consumer-Facing

Consumer-facing client applications SHALL obtain an access token for access to FHIR resources by following the OAuth 2.0 authorization code grant flow, as extended by the SMART App Launch Framework, and with the additional options and constraints discussed below.

Obtaining an authorization code

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

Constructing Authentication Token

If the client app has registered to authenticate using a private key rather than a shared client_secret, then 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. 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 Framework.

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

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.

Submitting a token request

For client applications authenticating with a shared secret, the client application and server SHALL follow the token request and response protocol in Section 7.1.3 of the HL7 SMART App Launch Framework.

Client applications authenticating with a private key and Authentication Token as per Section 4.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

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.