Merge pull request #250302 from MicrosoftDocs/release-healthcare-apis-toc

Release healthcare apis toc --scheduled release at 3PM of 9/05

Author: huypub

articles/healthcare-apis/authentication-authorization.md

@@ -1,5 +1,5 @@
 ---
-title: Azure Health Data Services Authentication and Authorization
+title: Authentication and authorization
 description: This article provides an overview of the authentication and authorization of Azure Health Data Services.
 services: healthcare-apis
 author: mikaelweave
@@ -9,15 +9,15 @@ ms.date: 06/06/2022
 ms.author: mikaelw
 ---
 
-# Authentication and Authorization for Azure Health Data Services
+# Authentication and authorization for Azure Health Data Services
 
 ## Authentication
 
  Azure Health Data Services is a collection of secured managed services using [Azure Active Directory (Azure AD)](../active-directory/index.yml), a global identity provider that supports [OAuth 2.0](https://oauth.net/2/).
 
-For the Azure Health Data Services to access Azure resources, such as storage accounts and event hubs, you must **enable the system managed identity**, and **grant proper permissions** to the managed identity. For more information, see [Azure managed identities](../active-directory/managed-identities-azure-resources/overview.md).
+For Azure Health Data Services to access Azure resources, such as storage accounts and event hubs, you must **enable the system managed identity**, and **grant proper permissions** to the managed identity. For more information, see [Azure managed identities](../active-directory/managed-identities-azure-resources/overview.md).
 
-Azure Health Data Services doesn't support other identity providers. However, customers can use their own identity provider to secure applications, and enable them to interact with the Health Data Services by managing client applications and user data access controls.
+Azure Health Data Services doesn't support other identity providers. However, you can use their own identity provider to secure applications, and enable them to interact with the Health Data Services by managing client applications and user data access controls.
 
 The client applications are registered in the Azure AD and can be used to access the Azure Health Data Services. User data access controls are done in the applications or services that implement business logic.
 
@@ -54,50 +54,50 @@ After being granted with proper application roles, the authenticated users and c
 
 There are two common ways to obtain an access token, outlined in detail by the Azure AD documentation: [authorization code flow](../active-directory/develop/v2-oauth2-auth-code-flow.md) and [client credentials flow](../active-directory/develop/v2-oauth2-client-creds-grant-flow.md).
 
-For obtaining an access token for the Azure Health Data Services, these are the steps using **authorization code flow**:
+Here's how an access token for Azure Health Data Services is obtained using **authorization code flow**:
 
 1. **The client sends a request to the Azure AD authorization endpoint.** Azure AD redirects the client to a sign-in page where the user authenticates using appropriate credentials (for example: username and password, or a two-factor authentication). **Upon successful authentication, an authorization code is returned to the client.** Azure AD only allows this authorization code to be returned to a registered reply URL configured in the client application registration.
 
-2. **The client application exchanges the authorization code for an access token at the Azure AD token endpoint.** When requesting a token, the client application may have to provide a client secret (which you can add during application registration).
+2. **The client application exchanges the authorization code for an access token at the Azure AD token endpoint.** When the client application requests a token, the application may have to provide a client secret (which you can add during application registration).
 
-3. **The client makes a request to the Azure Health Data Services**, for example, a `GET` request to search all patients in the FHIR service. When making the request, it **includes the access token in an `HTTP` request header**, for example, **`Authorization: Bearer xxx`**.
+3. **The client makes a request to the Azure Health Data Services**, for example, a `GET` request to search all patients in the FHIR service. The request **includes the access token in an `HTTP` request header**, for example, **`Authorization: Bearer xxx`**.
 
 4. **Azure Health Data Services validates that the token contains appropriate claims (properties in the token).** If it’s valid, it completes the request and returns data to the client.
 
 In the **client credentials flow**, permissions are granted directly to the application itself. When the application presents a token to a resource, the resource enforces that the application itself has authorization to perform an action since there’s no user involved in the authentication. Therefore, it’s different from the **authorization code flow** in the following ways:
 
-- The user or the client doesn’t need to log in interactively
+- The user or the client doesn’t need to sign in interactively.
 - The authorization code isn’t required.
 - The access token is obtained directly through application permissions.
 
 ### Access token
 
 The access token is a signed, [Base64](https://en.wikipedia.org/wiki/Base64) encoded collection of properties (claims) that convey information about the client's identity, roles, and privileges granted to the user or client.
 
-Azure Health Data Services typically expect a [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token). It consists of three parts:
+Azure Health Data Services typically expects a [JSON Web Token](https://en.wikipedia.org/wiki/JSON_Web_Token). It consists of three parts:
 
 * Header
 * Payload (the claims)
-* Signature, as shown in the image below. For more information, see [Azure access tokens](../active-directory/develop/configurable-token-lifetimes.md).
+* Signature, as shown in the image. For more information, see [Azure access tokens](../active-directory/develop/configurable-token-lifetimes.md).
 
 [ ![JASON web token signature.](media/azure-access-token.png) ](media/azure-access-token.png#lightbox)
 
-You can use online tools such as [https://jwt.ms](https://jwt.ms/) to view the token content. For example, you can view the claims details.
+Use online tools such as [https://jwt.ms](https://jwt.ms/) to view the token content. For example, you can view the claims details.
 
 |**Claim type**          |**Value**               |**Notes**                               |
 |------------------------|------------------------|----------------------------------------|
 |aud                     |https://xxx.fhir.azurehealthcareapis.com|Identifies the intended recipient of the token. In `id_tokens`, the audience is your app's Application ID, assigned to your app in the Azure portal. Your app should validate this value and reject the token if the value doesn’t match.|
-|iss                     |https://sts.windows.net/{tenantid}/|Identifies the security token service (STS) that constructs and returns the token, and the Azure AD tenant in which the user was authenticated. If the token was issued by the v2.0 endpoint, the URI will end in `/v2.0`. The GUID that indicates that the user is a consumer user from a Microsoft account is `9188040d-6c67-4c5b-b112-36a304b66dad`. Your app should use the GUID portion of the claim to restrict the set of tenants that can sign in to the app, if it's applicable.|
+|iss                     |https://sts.windows.net/{tenantid}/|Identifies the security token service (STS) that constructs and returns the token, and the Azure AD tenant in which the user was authenticated. If the token was issued by the v2.0 endpoint, the URI ends in `/v2.0`. The GUID that indicates that the user is a consumer user from a Microsoft account is `9188040d-6c67-4c5b-b112-36a304b66dad`. Your app should use the GUID portion of the claim to restrict the set of tenants that can sign in to the app, if it's applicable.|
 |iat                     |(time stamp)            |"Issued At" indicates when the authentication for this token occurred.|
 |nbf                     |(time stamp)            |The "nbf" (not before) claim identifies the time before which the JWT MUST NOT be accepted for processing.|
-|exp                     |(time stamp)            |The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. It's important to note that a resource may reject the token before this time as well, if for example, a change in authentication is required, or a token revocation has been detected.|
+|exp                     |(time stamp)            |The "exp" (expiration time) claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing. Note that a resource may reject the token before this time, for example if a change in authentication is required, or a token revocation has been detected.|
 |aio                     |E2ZgYxxx                |An internal claim used by Azure AD to record data for token reuse. Should be ignored.|
-|appid                   |e97e1b8c-xxx            |This is the application ID of the client using the token. The application can act as itself or on behalf of a user. The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.|
-|appidacr                |1                       |Indicates how the client was authenticated. For a public client, the value is "0". If client ID and client secret are used, the value is "1". If a client certificate was used for authentication, the value is "2".|
+|appid                   |e97e1b8c-xxx            |The application ID of the client using the token. The application can act as itself or on behalf of a user. The application ID typically represents an application object, but it can also represent a service principal object in Azure AD.|
+|appidacr                |1                       |Indicates how the client was authenticated. For a public client, the value is 0. If client ID and client secret are used, the value is 1. If a client certificate was used for authentication, the value is 2.|
 |idp                     |https://sts.windows.net/{tenantid}/|Records the identity provider that authenticated the subject of the token. This value is identical to the value of the Issuer claim unless the user account isn’t in the same tenant as the issuer - guests, for instance. If the claim isn’t present, it means that the value of iss can be used instead. For personal accounts being used in an organizational context (for instance, a personal account invited to an Azure AD tenant), the idp claim may be 'live.com' or an STS URI containing the Microsoft account tenant 9188040d-6c67-4c5b-b112-36a304b66dad.|
-|oid                     |For example, tenantid         |This is the immutable identifier for an object in the Microsoft identity system, in this case, a user account. This ID uniquely identifies the user across applications - two different applications signing in the same user will receive the same value in the oid claim. The Microsoft Graph will return this ID as the ID property for a given user account. Because the oid allows multiple apps to correlate users, the profile scope is required to receive this claim. Note: If a single user exists in multiple tenants, the user will contain a different object ID in each tenant - they’re considered different accounts, even though the user logs into each account with the same credentials.|
+|oid                     |For example, tenantid         |The immutable identifier for an object in the Microsoft identity system, in this case, a user account. This ID uniquely identifies the user across applications - two different applications signing in the same user receives the same value in the oid claim. The Microsoft Graph returns this ID as the ID property for a given user account. Because the oid allows multiple apps to correlate users, the profile scope is required to receive this claim. Note: If a single user exists in multiple tenants, the user contains a different object ID in each tenant - they’re considered different accounts, even though the user logs into each account with the same credentials.|
 |rh                       |0.ARoxxx              |An internal claim used by Azure to revalidate tokens. It should be ignored.|
-|sub                      |For example, tenantid        |The principal about which the token asserts information, such as the user of an app. This value is immutable and can’t be reassigned or reused. The subject is a pairwise identifier - it’s unique to a particular application ID. Therefore, if a single user signs into two different apps using two different client IDs, those apps will receive two different values for the subject claim. This may or may not be desired depending on your architecture and privacy requirements.|
+|sub                      |For example, tenantid        |The principle about which the token asserts information, such as the user of an app. This value is immutable and can’t be reassigned or reused. The subject is a pairwise identifier - it’s unique to a particular application ID. Therefore, if a single user signs into two different apps using two different client IDs, those apps receive two different values for the subject claim. You may or may not desire this result depending on your architecture and privacy requirements.|
 |tid                      |For example, tenantid        |A GUID that represents the Azure AD tenant that the user is from. For work and school accounts, the GUID is the immutable tenant ID of the organization that the user belongs to. For personal accounts, the value is 9188040d-6c67-4c5b-b112-36a304b66dad. The profile scope is required in order to receive this claim.
 |uti                      |bY5glsxxx             |An internal claim used by Azure to revalidate tokens. It should be ignored.|
 |ver                      |1                     |Indicates the version of the token.|

articles/healthcare-apis/azure-api-for-fhir/index.yml

@@ -1,7 +1,7 @@
 ### YamlMime:Landing
 
-title: Azure API for FHIR Documentation
-summary: Azure API for FHIR is a managed, standards-based, compliant API for clinical health data that enables solutions for actionable analytics and machine learning. 
+title: Azure API for FHIR documentation
+summary: Azure API for FHIR is a managed, standards-based, compliant API for clinical health data that enables actionable analytics and machine learning solutions. 
 
 metadata:
   title: Azure API for FHIR Documentation - tutorials, how-to guides
@@ -13,28 +13,26 @@ metadata:
   ms.collection: collection
   author: expekesheth
   ms.author: kesheth
-  ms.date: 09/30/2022
+  ms.date: 09/01/2023
 
 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new
 
 landingContent:
 
-  - title: Start with Azure API for FHIR
+  - title: Get started
     linkLists:
       - linkListType: overview
         links:
           - text: What is Azure API for FHIR?
             url: overview.md
-      - linkListType: quickstart
+      - linkListType: how-to-guide
         links:
           - text: Get started with Azure API for FHIR
             url: get-started-with-azure-api-fhir.md
-      - linkListType: deploy
-        links:
           - text: Deploy Azure API for FHIR
             url: fhir-paas-portal-quickstart.md
 
-  - title: Accessing Azure API for FHIR
+  - title: Access Azure API for FHIR
     linkLists:
       - linkListType: concept
         links:
@@ -58,7 +56,7 @@ landingContent:
           - text: Search examples for Azure API for FHIR
             url: search-samples.md 
 
-  - title: Interoperability and Patient Access
+  - title: Interoperability and patient access
     linkLists:
       - linkListType: tutorial
         links:
@@ -82,7 +80,7 @@ landingContent:
           - text: $member-match operation
             url: tutorial-member-match.md
 
-  - title: Export and Convert Data
+  - title: Export and convert data
     linkLists:
       - linkListType: how-to-guide
         links:

articles/healthcare-apis/azure-api-for-fhir/overview.md

@@ -6,14 +6,14 @@ author: expekesheth
 ms.service: healthcare-apis
 ms.subservice: fhir
 ms.topic: overview
-ms.date: 09/30/2022
+ms.date: 09/01/2023
 ms.author: kesheth
 ---
 
-# Azure API for FHIR Overview
+# What is Azure API for FHIR?
 
 > [!Note]
-> Azure Health Data services is the evolved version of Azure API for FHIR enabling customers to manage FHIR, DICOM, and MedTech services with integrations into other Azure Services. To learn about Azure Health Data Services [click here](https://azure.microsoft.com/products/health-data-services/).
+> Azure Health Data services is the evolved version of Azure API for FHIR enabling customers to manage FHIR, DICOM, and MedTech services with integrations into other Azure Services. 
 
 Azure API for FHIR enables rapid exchange of data through Fast Healthcare Interoperability Resources (FHIR®) APIs, backed by a managed Platform-as-a Service (PaaS) offering in the cloud. It makes it easier for anyone working with health data to ingest, manage, and persist Protected Health Information [PHI](https://www.hhs.gov/answers/hipaa/what-is-phi/index.html) in the cloud: 
 
@@ -29,11 +29,11 @@ Azure API for FHIR allows you to create and deploy a FHIR service in just minute
 
 The FHIR API and compliant data store enable you to securely connect and interact with any system that utilizes FHIR APIs.  Microsoft takes on the operations, maintenance, updates, and compliance requirements in the PaaS offering, so you can free up your own operational and development resources. 
 
-The following video presents an overview of Azure API for FHIR:
+This video presents an overview of Azure API for FHIR.
 
 >[!VIDEO https://www.youtube.com/embed/5vS7Iq9vpXE]
 
-## Leveraging the power of your data with FHIR
+## Leverage the power of your data with FHIR
 
 The healthcare industry is rapidly transforming health data to the emerging standard of [FHIR®](https://hl7.org/fhir). FHIR enables a robust, extensible data model with standardized semantics and data exchange that enables all systems using FHIR to work together. Transforming your data to FHIR allows you to quickly connect existing data sources such as the electronic health record systems or research databases. FHIR also enables the rapid exchange of data in modern implementations of mobile and web development. Most importantly, FHIR can simplify data ingestion and accelerate development with analytics and machine learning tools.  
 
@@ -49,7 +49,7 @@ You could invest resources building and running your own FHIR service, but with
 
 Using the Azure API for FHIR enables to you connect with any system that leverages FHIR APIs for read, write, search, and other functions. It can be used as a powerful tool to consolidate, normalize, and apply machine learning with clinical data from electronic health records, clinician and patient dashboards, remote monitoring programs, or with databases outside of your system that have FHIR APIs.
 
-### Control Data Access at Scale
+### Control data acess at scale
 
 You control your data. Role-based access control (RBAC) enables you to manage how your data is stored and accessed. Providing increased security and reducing administrative workload, you determine who has access to the datasets you create, based on role definitions you create for your environment.  
 
@@ -80,7 +80,7 @@ FHIR capabilities from Microsoft are available in two configurations:
 
 For use cases that require extending or customizing the FHIR server, or requires access to the underlying services—such as the database—without going through the FHIR APIs, developers should choose the open-source FHIR Server for Azure. For implementation of a turn-key, production-ready FHIR API and backend service where persisted data should only be accessed through the FHIR API, developers should choose the Azure API for FHIR.
 
-## Next Steps
+## Next steps
 
 To start working with Azure API for FHIR, follow the 5-minute quickstart to deploy the Azure API for FHIR.