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.