Update docs for smart v2

evachen96 · evachen96 · commit 1f4e621b9889 · 2025-11-24T16:02:33.000-05:00
diff --git a/articles/healthcare-apis/fhir/smart-on-fhir.md b/articles/healthcare-apis/fhir/smart-on-fhir.md
@@ -1,6 +1,6 @@
 ---
 title: SMART on FHIR - Azure Health Data Services
-description: This tutorial describes how to use a proxy to enable SMART on FHIR applications with the FHIR service.
+description: This tutorial describes how to enable SMART on FHIR applications with the FHIR service.
 services: healthcare-apis
 ms.service: azure-health-data-services
 ms.subservice: fhir
@@ -23,7 +23,7 @@ The following tutorials provide steps to enable SMART on FHIR applications with
 ## Prerequisites
 
 - An instance of the FHIR Service
-- .NET SDK 6.0
+- .NET SDK 8.0
 - [Enable cross-origin resource sharing (CORS)](configure-cross-origin-resource-sharing.md)
 - [Register public client application in Microsoft Entra ID](/azure/healthcare-apis/azure-api-for-fhir/register-public-azure-ad-client-app)
      - After registering the application, make note of the `applicationId` for client application.
@@ -38,18 +38,68 @@ Follow the steps listed in section [Manage Users: Assign Users to Role](/azure/r
 > SMART on FHIR Implementation Guide defines access to FHIR resource types with scopes. These scopes impact the access an application may have to FHIR resources. A user with the SMART user role has access to perform read API interactions on FHIR service. SMART user role does not grant write access to FHIR service.
 
 ### Step 2: FHIR server integration with samples
-**[Click on this link](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir)** to navigate to Azure Health Data and AI Samples open source solution. The steps listed in the document enable integration of FHIR server with other Azure Services (such as APIM, Azure functions and more).
+Azure Health Data and AI Samples open source repo provides samples for [SMART on FHIR v1.0.0](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir) and [SMART on FHIR v2.0.0](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir-smart-v2). The steps listed in the document enable integration of FHIR server with other Azure Services (such as APIM, Azure functions and more).
 
 > [!NOTE]
 > Samples are open-source code, and you should review the information and licensing terms on GitHub before using it. They are not part of the Azure Health Data Service and are not supported by Microsoft Support. These samples are used to demonstrate how Azure Health Data Services (AHDS) and other open-source tools can be used together to demonstrate [§170.315(g)(10) Standardized API for patient and population services criterion](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg) compliance, using Microsoft Entra ID as the identity provider workflow.  
 
+ 
+
+The following lists the different scopes supported in SMART v1.0.0 and SMART v2.0.0. Please note that you cannot mix and match SMART v1.0.0 and SMART v.2.0.0 scopes in the same client app registration; you must choose one or the other. 
+
+#### SMART v1: 
+[SMART on FHIR v1.0.0 sample](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir)
+
+
+Scopes:
+
+- patient/Observation.read 
+
+- user/Encounter.* 
+
+- patient/*.* 
+
+- system/Patient.read (commonly used for $export) 
+
+ 
+
+#### SMART v2: 
+ [SMART on FHIR v2.0.0 sample](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir-smart-v2)
+- Granular scopes: 
+
+    - r = read only 
+    
+    - s = search 
+    
+    - rs = read+search 
+    
+      - NOTE: rs scopes allow both direct reads and search operations; r alone does not allow any search or _include on direct record lookup. 
+
+
+- To map from SMART v1 scopes to SMART v2 scopes, use the following table:  
+ 
+| SMART v1 Scope          | SMART v2 Scope         |
+|------------------------|-----------------------|
+| patient/Observation.read | Patient/Observation.rs |
+| patient/*.read | Patient/*.rs | 
+| system/Patient.read | System/Patient.rs |
+
+- Parameter-constrained scopes:
+  - SMART v2 expands on standard scopes by introducing parameter-constrained scopes, allowing clients to access only the subset of resources matching specific query parameters.  
+    - Example: `Condition.rs?category=http//terminology.hl7.org/CodeSystem/condition-category|encounter-diagnosis`  
+    -   This scope grants read/search access only to Condition resources with that specific category. 
+  - Note: Chained, `_include`, and `_revinclude` are only supported in the normal search query, they are not supported in the granular scope query string.  
+
+
+
 ## SMART on FHIR Proxy
 <details>
                 <summary> Click to expand! </summary>
 
 > [!NOTE]
 > This is another option to SMART on FHIR(Enhanced) using the AHDS Samples previously mentioned. We suggest you to adopt SMART on FHIR(Enhanced). SMART on FHIR Proxy option is a legacy option.
-> SMART on FHIR(Enhanced) provides added capabilities to SMART on FHIR proxy. SMART on FHIR(Enhanced) meets requirements in [SMART on FHIR Implementation Guide (v 1.0.0)](https://hl7.org/fhir/smart-app-launch/1.0.0/) and [§170.315(g)(10) Standardized API for patient and population services criterion](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg).
+> SMART on FHIR(Enhanced) provides added capabilities to SMART on FHIR proxy. SMART on FHIR(Enhanced) meets requirements in [SMART on FHIR Implementation Guide (v 1.0.0)](https://hl7.org/fhir/smart-app-launch/1.0.0/), [SMART on FHIR Implementation Guide (v 2.0.0)](https://hl7.org/fhir/smart-app-launch/STU2/),  and [§170.315(g)(10) Standardized API for patient and population services criterion](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg).
+
 
 ### Step 1: Set admin consent for your client application
 
diff --git a/articles/healthcare-apis/includes/smart-on-fhir-proxy-migration.md b/articles/healthcare-apis/includes/smart-on-fhir-proxy-migration.md
@@ -12,8 +12,8 @@ ms.custom: "include file"
 > [!IMPORTANT]
 > **SMART on FHIR proxy is retiring in September 2026**, transition to the SMART on FHIR (Enhanced) by that date. Beginning September 2026, applications relying on SMART on FHIR proxy will report errors in accessing the FHIR service.
 
-SMART on FHIR (Enhanced) provides more capabilities compared to SMART on FHIR proxy. SMART on FHIR(Enhanced) can be considered to meet requirements with [SMART on FHIR Implementation Guide (v 1.0.0)](https://hl7.org/fhir/smart-app-launch/1.0.0/) and [§170.315(g)(10) Standardized API for patient and population services criterion.](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg)
-The following table lists the difference between SMART on FHIR proxy and SMART on FHIR (Enhanced).
+SMART on FHIR (Enhanced) provides more capabilities compared to SMART on FHIR proxy. SMART on FHIR(Enhanced) can be considered to meet requirements with [SMART on FHIR Implementation Guide (v 1.0.0)](https://hl7.org/fhir/smart-app-launch/1.0.0/), [SMART on FHIR Implementation Guide (v 2.0.0)](https://hl7.org/fhir/smart-app-launch/STU2/),  and [§170.315(g)(10) Standardized API for patient and population services criterion.](https://www.healthit.gov/test-method/standardized-api-patient-and-population-services#ccg)
+The following table lists the difference between SMART on FHIR proxy and SMART on FHIR (Enhanced). SMART on FHIR Implementation Guide (v2.0.0) is only supported in SMART on FHIR (Enhanced) sample. 
 
 |Capability|SMART on FHIR (Enhanced)|SMART on FHIR proxy|
 |---|---|---|
@@ -26,7 +26,7 @@ The following table lists the difference between SMART on FHIR proxy and SMART o
 ### Migration Steps
 * Step 1: Set up FHIR SMART user role 
 Follow the steps listed under section [Manage Users: Assign Users to Role](/azure/active-directory/fundamentals/active-directory-users-assign-role-azure-portal). Any user added to SMART user role is able to access the FHIR Service, if their requests comply with the SMART on FHIR implementation Guide. 
-* Step 2: Deploy SMART on FHIR sample under [Azure Health Data and AI OSS samples](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir)
+* Step 2: Deploy SMART on FHIR sample under Azure Health Data and AI OSS samples - [SMART v1](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir) or [SMART v2](https://github.com/Azure-Samples/azure-health-data-and-ai-samples/tree/main/samples/smartonfhir-smart-v2).
 * Step 3: Update endpoint of the FHIR service url to '{{BASEURL_FROM_APIM}}/smart.'
 * Step 4: Uncheck the SMART on FHIR proxy setting under Authentication blade for the FHIR service. 
 
