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 3.0.0-current 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

Consumer-Facing

Page standards status: Trial-use

This guide supports consumer-facing client applications using the authorization code grant type.

Consumer-facing client applications SHALL obtain access tokens for access to protected resources by following the OAuth 2.0 authorization code grant flow, with the additional options and constraints discussed below.

Authorization code workflow

The workflow for obtaining an access token using this grant type is summarized in the following diagram:

Client applications and Authorization Servers SHALL conform to the additional constraints for scope negotiation found in Section 7.2.

Client applications and Authorization Servers SHALL utilize Proof Key for Code Exchange (PKCE) with code_challenge_method of S256 as defined in RFC 7636.

Authorization request

Client applications SHALL request an authorization code as per Section 4.1.1 of RFC 6749, with the following additional constraints. Client applications and servers MAY optionally support UDAP Tiered OAuth for User Authentication to allow for cross-organizational or third party user authentication as described in Section 6.

Authorization Servers SHALL support both GET and POST requests to their authorization endpoint for the authorization code flow. Clients SHALL support at least one of these two HTTP methods. 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.
code_challenge	required	PKCE code challenge.
code_challenge_method	required	Fixed value: S256

Authorization response

Servers SHALL handle and respond to authorization code requests as per Section 4.1.2 of RFC 6749.

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.

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

Token request

Client applications SHALL exchange authorization codes for access tokens as per Section 4.1.3 of RFC 6749, with the following additional options and constraints.

Client applications SHALL generate an Authentication Token JWT as detailed Section 4.2.

Client applications SHALL submit a POST request to the Authorization Server’s token endpoint as per Section 5.1 of UDAP JWT-Based Client Authentication. A client application authenticating in this manner SHALL NOT include an HTTP Authorization header or client secret in its token 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
code_verifier	required	The code verifier corresponding to the PKCE code challenge included by the client in the authorization request, as per Section 4.5 of RFC 7636.
redirect_uri	conditional	The client application's redirection URI. This parameter SHALL be present only if the redirect_uri parameter was included in the authorization request in Section 4.1.1, and their values SHALL be identical.
client_assertion_type	required	Fixed value: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion	required	The signed Authentication Token JWT constructed as per Section 4.2.
udap	required	Fixed value: 1

Token response

Authorization Servers SHALL validate and respond to token requests as per Sections 6 and 7 of UDAP JWT-Based Client Authentication, with the additional constraints below.

Authorization Servers SHALL return an error 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_verifier value in the corresponding token request.

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

Constructing an Authentication Token

Client apps 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 4.1.3] of this guide.

Authentication Tokens submitted by client apps SHALL conform to the general JWT header requirements in Section 7.1 of this guide and SHALL include the following parameters in the JWT claims, as defined in Section 4 of UDAP JWT-Based Client Authentication:

Authentication JWT Claims
iss	required	The application's client_id as assigned by the Authorization Server during the registration process
sub	required	The application's client_id as assigned by the Authorization Server during the registration process
aud	required	The 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. See Section 7.1.4 for additional requirements regarding reuse of values.

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.

Refresh token workflow

This guide supports the use of refresh tokens, as described in Section 1.5 of RFC 6749. Authorization Servers MAY issue refresh tokens to consumer-facing client applications as per Section 5 of RFC 6749. Client apps that have been issued refresh tokens MAY make refresh requests to the token endpoint as per Section 6 of RFC 6749.

The workflow for obtaining an access token using this grant type is summarized in the following diagram:

Client apps authenticate to the Authorization Server for refresh requests by constructing and including an Authentication Token in the same manner as for initial token requests.