Update 1: Mandatory PKCE Implementation for Smart on FHIR Apps

As part of the Regulatory Requirements HTI1, we are mandating the Proof Key for Code Exchange (PKCE) for all Smart on FHIR apps. Below, you will find important details regarding PKCE, why it is required, guidelines on how to implement it, the deadline for completing the changes, and the implications of not making the changes on time.

What is PKCE?

PKCE (Proof Key for Code Exchange) is an extension to the OAuth 2.0 authorization framework. It enhances the security of OAuth clients by mitigating the risk of authorization code interception attacks. PKCE achieves this by requiring the client to generate a code verifier and a code challenge during the authorization request, which are then used to securely exchange the authorization code for an access token.

Why is it required?

PKCE is required to ensure the security and integrity of the authorization process for Smart on FHIR clients. By implementing PKCE, we can prevent malicious actors from intercepting authorization codes and gaining unauthorized access to sensitive health information. This requirement aligns with the regulatory standards set forth by HTI1 to enhance the security of Smart on FHIR applications.

Guidelines on How to Implement PKCE:

1. Generate a Code Verifier: The client creates a random string called the code verifier.
2. Create a Code Challenge: The client creates a code challenge by applying a transformation (S256) to the code verifier. Also, the Greenway Authorization Server will support only the S256 code challenge method and will stop supporting the plain method after September 30, 2025. If you are using the plain method, please switch to S256 before September 30, 2025.
3. Include Code Challenge in Authorization Request: The client includes the code challenge in the authorization request to the authorization server.
4. Exchange Authorization Code for Access Token: When exchanging the authorization code for an access token, the client sends the code verifier to the authorization server. The server verifies the code challenge against the code verifier before issuing the access token.

For implementation details, please refer SMART 2.0 implementation guide.

📘

Deadline for Completing the Changes

All Smart on FHIR clients must implement S256 based PKCE by September 30, 2025. This deadline is critical to ensure compliance with the regulatory requirements and to maintain the security of Smart On FHIR applications.

Implications of Not Making the Changes on Time

Effective from September 30, 2025, we will no longer support requests that do not use PKCE or that use the PKCE plain code challenge method. Applications attempting to connect without PKCE and the S256 code challenge method will not be issued access tokens until they are updated to comply with these requirements.

We would like to ask you to prioritize implementing PKCE to ensure the security and compliance of your applications.

Update 2: Update Intended User(s) and Intended Purpose(s) for Existing Apps

It is now a regulatory requirement to add two new fields to the app registration process: Intended User(s) and Intended Purpose(s).These fields are now mandatory for all apps and must be defined to ensure compliance with ONC insights reporting requirements.

📘

Action Required:

• Update the Intended User(s) and Intended Purpose(s) fields with the appropriate information in the Edit App screen.

We kindly request that you complete these updates as soon as possible.

Steps to Update the Intended User(s) and Intended Purpose(s) Fields for Already Registered Apps:

1. Log in to the Developer Platform.
2. On the application dashboard, you will see a banner stating: “Please note: Intended User(s) and Intended Purpose(s) fields must be defined for all apps. Add them on the Edit App screen, if at least one app has not had its Intended Purpose(s) and Intended User(s) updated.
3. Open the App Details screen for the app you want to update.
4. Select the pencil icon to edit the General Information section.
5. Update the Intended User(s) and Intended Purpose(s) fields.
6. Select the Save App button.