Extra edits

Author: cdpark

articles/ai-services/immersive-reader/how-to-store-user-preferences.md

@@ -26,7 +26,7 @@ This functionality may be used as an alternate means to storing **user preferenc
 
 ## How to enable storing user preferences
 
-the Immersive Reader SDK [launchAsync](./reference.md#launchasync) `options` parameter contains the `-onPreferencesChanged` callback. This function will be called anytime the user changes their preferences. The `value` parameter contains a string, which represents the user's current preferences. This string is then stored, for that user, by the host application.
+the Immersive Reader SDK [launchAsync](reference.md#function-launchasync) `options` parameter contains the `-onPreferencesChanged` callback. This function will be called anytime the user changes their preferences. The `value` parameter contains a string, which represents the user's current preferences. This string is then stored, for that user, by the host application.
 
 ```typescript
 const options = {

articles/ai-services/immersive-reader/reference.md

@@ -1,7 +1,7 @@
 ---
 title: Immersive Reader SDK Javascript reference
 titleSuffix: Azure AI services
-description: Learn about the Immersive Reader JavaScript library that allows you to integrate the Immersive Reader into your application.
+description: Learn about the Immersive Reader JavaScript library that allows you to integrate Immersive Reader into your application.
 #services: cognitive-services
 author: sharmas
 manager: nitinme
@@ -49,18 +49,18 @@ launchAsync(token: string, subdomain: string, content: Content, options?: Option
 
 | Parameter | Type | Description |
 | ---- | ---- |------------ |
-| `token` | string | The Microsoft Entra authentication token. To learn more, see [How to create an Immersive Reader resource](how-to-create-immersive-reader.md). |
-| `subdomain` | string | The custom subdomain of your [Immersive Reader resource](how-to-create-immersive-reader.md) in Azure. |
-| `content` | [Content](#content) | An object that contains the content to be shown in the Immersive Reader. |
-| `options` | [Options](#options) | Options for configuring certain behaviors of the Immersive Reader. Optional. |
+| token | string | The Microsoft Entra authentication token. To learn more, see [How to create an Immersive Reader resource](how-to-create-immersive-reader.md). |
+| subdomain | string | The custom subdomain of your [Immersive Reader resource](how-to-create-immersive-reader.md) in Azure. |
+| content | [Content](#content) | An object that contains the content to be shown in the Immersive Reader. |
+| options | [Options](#options) | Options for configuring certain behaviors of the Immersive Reader. Optional. |
 
 #### Returns
 
 Returns a `Promise<LaunchResponse>`, which resolves when the Immersive Reader is loaded. The `Promise` resolves to a [LaunchResponse](#launchresponse) object.
 
 #### Exceptions
 
-The returned `Promise` is rejected with an [Error](#error) object if the Immersive Reader fails to load.
+If the Immersive Reader fails to load, the returned `Promise` is rejected with an [Error](#error) object.
 
 ### Function: `close`
 
@@ -95,7 +95,7 @@ renderButtons(options?: RenderButtonsOptions): void;
 
 | Parameter | Type | Description |
 | ---- | ---- |------------ |
-| `options` | [renderButtons options](#renderbuttons-options) | Options for configuring certain behaviors of the renderButtons function. Optional. |
+| options | [renderButtons options](#renderbuttons-options) | Options for configuring certain behaviors of the renderButtons function. Optional. |
 
 #### renderButtons options
 
@@ -128,9 +128,9 @@ Use the following optional attributes to configure the look and feel of the butt
 
 | Attribute | Description |
 | --------- | ----------- |
-| `data-button-style` | Sets the style of the button. Can be `icon`, `text`, or `iconAndText`. Defaults to `icon`. |
-| `data-locale` | Sets the locale. For example, `en-US` or `fr-FR`. Defaults to English `en`. |
-| `data-icon-px-size` | Sets the size of the icon in pixels. Defaults to 20 px. |
+| data-button-style | Sets the style of the button. Can be `icon`, `text`, or `iconAndText`. Defaults to `icon`. |
+| data-locale | Sets the locale. For example, `en-US` or `fr-FR`. Defaults to English `en`. |
+| data-icon-px-size | Sets the size of the icon in pixels. Defaults to 20 px. |
 
 ## LaunchResponse
 
@@ -332,16 +332,15 @@ Default value: null
 ```
 
 ##### `preferences`
-
-> [!CAUTION]
-> Don't attempt to programmatically change the values of the `-preferences` string sent to and from the Immersive Reader application because this might cause unexpected behavior resulting in a degraded user experience. Host applications should never assign a custom value to or manipulate the `-preferences` string. When using the `-preferences` string option, use only the exact value that was returned from the `-onPreferencesChanged` callback option.
-
 ```Parameters
 Type: String
 Required: false
 Default value: null
 ```
 
+> [!CAUTION]
+> Don't attempt to programmatically change the values of the `-preferences` string sent to and from the Immersive Reader application because this might cause unexpected behavior resulting in a degraded user experience. Host applications should never assign a custom value to or manipulate the `-preferences` string. When using the `-preferences` string option, use only the exact value that was returned from the `-onPreferencesChanged` callback option.
+
 ##### `onPreferencesChanged`
 ```Parameters
 Type: Function
@@ -372,6 +371,9 @@ type ReadAloudOptions = {
 | speed | Number | Playback speed. Must be between 0.5 and 2.5, inclusive. |
 | autoPlay | Boolean | Automatically start Read Aloud when the Immersive Reader loads. |
 
+> [!NOTE]
+> Due to browser limitations, autoplay is not supported in Safari.
+
 ##### `voice`
 ```Parameters
 Type: String
@@ -388,9 +390,6 @@ Default value: 1
 Values available: 0.5, 0.75, 1, 1.25, 1.5, 1.75, 2, 2.25, 2.5
 ```
 
-> [!NOTE]
-> Due to browser limitations, autoplay is not supported in Safari.
-
 ## TranslationOptions
 
 ```typescript

articles/ai-services/immersive-reader/security-how-to-update-role-assignment.md

@@ -15,27 +15,27 @@ ms.author: sharmas
 
 # Security advisory: Update role assignment for Microsoft Entra authentication
 
-A security bug was discovered with Immersive Reader Microsoft Entra authentication configuration. We advise that you change the permissions on your Immersive Reader resources.
+A security bug was discovered that affects Microsoft Entra authentication for Immersive Reader. We advise that you change the permissions on your Immersive Reader resources.
 
 ## Background
 
-A security bug was discovered that relates to Microsoft Entra authentication for Immersive Reader. When initially creating your Immersive Reader resources and configuring them for Microsoft Entra authentication, it's necessary to grant permissions for the Microsoft Entra application identity to access your Immersive Reader resource. This is known as a *role assignment*. The Azure role that was previously used for permissions was the [Cognitive Services User](../../role-based-access-control/built-in-roles.md#cognitive-services-user) role.
+When you initially create your Immersive Reader resources and configure them for Microsoft Entra authentication, it's necessary to grant permissions for the Microsoft Entra application identity to access your Immersive Reader resource. This is known as a *role assignment*. The Azure role that was previously used for permissions was the [Cognitive Services User](../../role-based-access-control/built-in-roles.md#cognitive-services-user) role.
 
-During a security audit, it was discovered that this Cognitive Services User role has permissions to [list keys](/rest/api/cognitiveservices/accountmanagement/accounts/list-keys). This is slightly concerning because Immersive Reader integrations involve the use of this Microsoft Entra access token in client web apps and browsers, and if the access token were stolen by a bad actor or attacker, there's a concern that this access token could be used to `list keys` of your Immersive Reader resource. If an attacker could `list keys` for your resource, then they would obtain the `Subscription Key` for your resource. The `Subscription Key` for your resource is used as an authentication mechanism and is considered a secret. If an attacker had the resource's `Subscription Key`, it would allow them to make valid and authenticated API calls to your Immersive Reader resource endpoint, which could lead to Denial of Service due to the increased usage and throttling on your endpoint. It would also allow unauthorized use of your Immersive Reader resource, which would lead to increased charges on your bill.
+During a security audit, it was discovered that this Cognitive Services User role has permissions to [list keys](/rest/api/cognitiveservices/accountmanagement/accounts/list-keys). This is slightly concerning because Immersive Reader integrations involve the use of this Microsoft Entra access token in client web apps and browsers. If the access token were stolen by a bad actor or attacker, there's a concern that this access token could be used to `list keys` for your Immersive Reader resource. If an attacker could `list keys` for your resource, then they would obtain the `Subscription Key` for your resource. The `Subscription Key` for your resource is used as an authentication mechanism and is considered a secret. If an attacker had the resource's `Subscription Key`, it would allow them to make valid and authenticated API calls to your Immersive Reader resource endpoint, which could lead to Denial of Service due to the increased usage and throttling on your endpoint. It would also allow unauthorized use of your Immersive Reader resource, which would lead to increased charges on your bill.
 
-In practice however, this attack or exploit isn't likely to occur or might not even be possible. For Immersive Reader scenarios, customers obtain Microsoft Entra access tokens with an audience of `https://cognitiveservices.azure.com`. In order to successfully `list keys` for your resource, the Microsoft Entra access token would need to have an audience of `https://management.azure.com`. Generally speaking, this isn't much of a concern, since the access tokens used for Immersive Reader scenarios wouldn't work to `list keys`, as they don't have the required audience. In order to change the audience on the access token, an attacker would have to hijack the token acquisition code and change the audience before the call is made to Microsoft Entra ID to acquire the token. Again, this isn't likely to be exploited because, as an Immersive Reader authentication best practice, we advise that customers create Microsoft Entra access tokens on the web application backend, not in the client or browser. In those cases, since the token acquisition happens on the backend service, it's not as likely or perhaps even possible that attacker could compromise that process and change the audience.
+In practice, however, this attack or exploit isn't likely to occur or might not even be possible. For Immersive Reader scenarios, customers obtain Microsoft Entra access tokens with an audience of `https://cognitiveservices.azure.com`. In order to successfully `list keys` for your resource, the Microsoft Entra access token would need to have an audience of `https://management.azure.com`. Generally speaking, this isn't much of a concern, since the access tokens used for Immersive Reader scenarios wouldn't work to `list keys`, as they don't have the required audience. In order to change the audience on the access token, an attacker would have to hijack the token acquisition code and change the audience before the call is made to Microsoft Entra ID to acquire the token. Again, this isn't likely to be exploited because, as an Immersive Reader authentication best practice, we advise that customers create Microsoft Entra access tokens on the web application backend, not in the client or browser. In those cases, since the token acquisition happens on the backend service, it's not as likely or perhaps even possible that an attacker could compromise that process and change the audience.
 
 The real concern comes when or if any customer were to acquire tokens from Microsoft Entra ID directly in client code. We strongly advise against this, but since customers are free to implement as they see fit, it's possible that some customers are doing this.
 
-To mitigate the concerns about any possibility of using the Microsoft Entra access token to `list keys`, we created a new built-in Azure role called `Cognitive Services Immersive Reader User` that doesn't have the permissions to `list keys`. This new role isn't a shared role for the Azure AI services platform like `Cognitive Services User` role is. This new role is specific to Immersive Reader and will only allow calls to Immersive Reader APIs.
+To mitigate the concerns about any possibility of using the Microsoft Entra access token to `list keys`, we created a new built-in Azure role called `Cognitive Services Immersive Reader User` that doesn't have the permissions to `list keys`. This new role isn't a shared role for the Azure AI services platform like `Cognitive Services User` role is. This new role is specific to Immersive Reader and only allows calls to Immersive Reader APIs.
 
 We advise ALL customers to use the new `Cognitive Services Immersive Reader User` role instead of the original `Cognitive Services User` role. We have provided a script below that you can run on each of your resources to switch over the role assignment permissions.
 
 This recommendation applies to ALL customers, to ensure that this vulnerability is patched for everyone, no matter what the implementation scenario or likelihood of attack.
 
 If you do NOT do this, nothing will break. The old role will continue to function. The security impact for most customers is minimal. However, we advise that you migrate to the new role to mitigate the security concerns discussed. Applying this update is a security advisory recommendation; it's not a mandate.
 
-Any new Immersive Reader resources you create with our script at [How to: Create an Immersive Reader resource](./how-to-create-immersive-reader.md) automatically uses the new role.
+Any new Immersive Reader resources you create with our script at [How to: Create an Immersive Reader resource](./how-to-create-immersive-reader.md) automatically use the new role.
 
 ## Update role and rotate your subscription keys
 
@@ -135,7 +135,7 @@ You can rotate the subscription keys in the [Azure portal](https://portal.azure.
     | Parameter | Comments |
     | --- | --- |
     | SubscriptionName |The name of your Azure subscription. |
-    | ResourceGroupName |The name of the Resource Group that contains your Immersive Reader resource. |
+    | ResourceGroupName |The name of the resource group that contains your Immersive Reader resource. |
     | ResourceName |The name of your Immersive Reader resource. |
     | AADAppIdentifierUri |The URI for your Microsoft Entra app. |