Dynamic Client Registration

Intro / Motivation

To support friction-less data exchange, health applications need a scalable way to register with health data systems across the ecosystem. Dynamic registration is a standards-based technical protocol to cover the "mechanical" part of introducing a client to a server.

Is this the Wild West?

There can be be many policies gating registration, including:

1. Totally open registration
2. Registration only for clients that have been endorsed or pre-approved
3. Only allow registration when a valid Authorization header is provided

And after completing registration, an app may still require authorization before it can access data. For example, patient-facing apps require authorization from a patient after registration and before retrieving data.

Profiling OAuth 2.0 Dyn Reg

This specification profiles RFC7591 (OAuth 2.0 Dynamic Client Registration Protocol) for three key use cases:

• User-facing confidential clients. For example, conventional server-based web applications that can maintain a secret, or long-lived on-device mobile applications that can be registered on each individual device where they run (so secrets are not shared across devices).

• User-facing public clients. With dynamic registration, a larger class of apps can be registered as confidential clients, since each copy of the app can maintain its own secret. Public client registration is still suitable for short-lived apps, such as browser-based apps that users interact with transiently.

• Backend services. For business-to-business connections, backend services can access data directly, without a user directly in the loop.

OAuth Dynamic Registration: Parameters

The following general metadata apply to a dynamic registration process, as defined by RFC7591:

Parameter	Description
client_name	(Mandatory) Name for the client application
client_uri	(Optional) home page for app
logo_uri	(Optional) img src for app icon
software_id	(Optional) identifier for the software
software_version	(Optional) version for the software
scope	(Optional) scopes the client is asking
tos_uri	(Optional) URL string that points to a human-readable terms of service document, per RFC7591
policy_uri	(Optional) URL string that points to a human-readable privacy policy document
contacts	(Optional) per RFC7591
jwks_uri	(Optional) per RFC7591
jwks	(Optional) per RFC7591
response_types	(Required for user-facing apps) Array of the OAuth 2.0 response type strings, per RFC7591
redirect_uris	(Required for user-facing apps) list of fully-fixed redirect URIs allowed for the client
token_endpoint_auth_method	(Required) String indicator of the requested authentication method for the token endpoint, per RFC7591
grant_types	(Required) Array of allowed grant types, per RFC7591

The following SMART-defined extension parameters are defined:

Parameter	Description
initiate_login_uri	(Required for apps supporting SMART EHR Launch flow) uri to launch the application
endorsements	(Optional) a list of JWTs provided by various endorsing authorities (see https://github.com/HHSIDEAlab/poet for an overview of this concept)

Using Endorsements

At registration time, an app can present an endorsement in the form of a signed JWT issued by a third party (an Endorser), containing claims that can help ensure a higher level of trust in the registration. See https://github.com/HHSIDEAlab/poet for an approach to encoding these endorsements, and see http://wiki.hl7.org/index.php?title=201809_Direct/Certificates_Track#Overview_of_Scenario_2 for an overview of another in-progress project (?? note: I don't think there is public documentation available).

Critically, any endorsement presented by an app must be appropriately bound to the app (i.e., to prevent one app from trying to pass along another app's endorsements). Approaches for binding an endorsement to an app's registration include:

1. Asymmetric cryptography. If the app can maintain a private key, then a signed endorsement can include this key. For example, this can be done with a cryptographic certificate.

2. Property binding. Even if an app cannot maintain a private key, a signed endorsement can include app registration data including (critically) its redirect_uris, client_uri, and client_name.

Registering Confidential Client SMART Apps

In addition to the general metadata, an app must supply

• token_endpoint_auth_method: client_secret_basic (fixed value)
• grant_types: authorization_code (fixed value)
• response_types: code (fixed value)
• redirect_uris: list of fully-fixed redirect URIs allowed for the client

Registering Public Client SMART Apps

In addition to the general metadata, an app must supply

• grant_types: authorization_code (fixed value)
• response_types: code (fixed value)
• redirect_uris: list of fully-fixed redirect URIs allowed for the client

Registering Backend Services

• token_endpoint_auth_method: private_key_jwt (fixed value)
• response_types: token (fixed value)
• jwks or jwks_uri

(Future): Confidential Clients with Asymmetric Authentication

Today, SMART does not define support for a confidential client with asymmetric authentication. But especially in a wide ecosystem of dynamic registration, clients holding a private key reduce the burden of generating and securely sharing client_secret values between apps and EHRs.

• token_endpoint_auth_method = private_key_jwt
• grant_types = authorization_code
• response_types = code
• redirect_uris list of allowed redirect uris for the client

Presenting vendor-specific questions and answers

Today, different vendor-specific registration procedures require app developers to answer specific questions in order to proceed. These answers could readily be included as extension parameters in a dynamic client registration payload -- or represented within an endorsement.

• Which option best describes the company offering the app to users/patients?
• Do you have a business associate agreement with each covered entity your app will connect to?
• How is this app funded? (Select all that apply.)
• Where does this app store user data? (Select all that apply.)
• Other than the user, who has access to user data? (Select all that apply.)
• For entities that can access user data, will the user specifically approve and be notified of each access to user's data, or is their authorization general and information shared without notification?
• Does this app allow users to obtain a record of the data that it has collected about them?
• Does this app allow users to delete the data it has stored about them?
• Is user health information retained after a user deletes the app and closes their account?
• Other than providing direct service to the user, how does this app use data about the user? (Select all that apply.)
• For how long does this app store user data?
• Does this app allow users to obtain a record of who has accessed data about them?