Merge pull request #221579 from cebundy/sigr-upstream

[SignalR Service]: Change upstream to upstream endpoints

Author: Court72

articles/azure-signalr/TOC.yml

@@ -67,7 +67,7 @@
       href: signalr-concept-serverless-development-config.md
     - name: SignalR Service bindings for Azure Functions reference
       href: ../azure-functions/functions-bindings-signalr-service.md
-    - name: Upstream settings
+    - name: Configure upstream endpoints
       href: concept-upstream.md
   - name: High availability
     items:

articles/azure-signalr/concept-service-mode.md

@@ -59,7 +59,7 @@ Serverless mode doesn't have connection stickiness, but you can still have a ser
 > [!NOTE]
 > Both REST API and WebSockets are supported in SignalR service [management SDK](https://github.com/Azure/azure-signalr/blob/dev/docs/management-sdk-guide.md). If you're using a language other than .NET, you can also manually invoke the REST APIs following this [specification](https://github.com/Azure/azure-signalr/blob/dev/docs/rest-api.md).
 
-It's also possible for your server application to receive messages and connection events from clients. SignalR Service will deliver messages and connection events to pre-configured endpoints (called *upstream endpoints*) using web hooks. Upstream endpoints can only be configured in Serverless mode. For more information, see [Upstream settings](concept-upstream.md).
+It's also possible for your server application to receive messages and connection events from clients. SignalR Service will deliver messages and connection events to pre-configured endpoints (called *upstream endpoints*) using web hooks. Upstream endpoints can only be configured in Serverless mode. For more information, see [Upstream endpoints](concept-upstream.md).
 
 
 

articles/azure-signalr/concept-upstream.md

@@ -1,41 +1,41 @@
 ---
-title: Upstream settings in Azure SignalR Service
-description: Get an introduction of upstream settings and protocols of upstream messages.
+title: Upstream endpoints in Azure SignalR Service
+description: Introduction to upstream endpoints settings and upstream message protocols.
 author: vicancy
 ms.service: signalr
 ms.topic: conceptual
 ms.date: 12/09/2022
 ms.author: lianwei
 ---
 
-# Upstream settings
+# Upstream endpoints
 
-Upstream is a feature that allows Azure SignalR Service to send messages and connection events to a set of endpoints in serverless mode. You can use upstream to invoke a hub method from clients in serverless mode and let endpoints get notified when client connections are connected or disconnected.
+The upstream endpoints feature allows Azure SignalR Service to send messages and connection events to a set of endpoints in serverless mode. You can use upstream endpoints to invoke a hub method from clients in serverless mode to notify endpoints when client connections are connected or disconnected.
 
 > [!NOTE]
-> Only serverless mode can configure upstream settings.
+> Upstream endpoints can only be configured in serverless mode.
 
-## Details of upstream settings
+## Upstream endpoint settings
 
-Upstream settings consist of a list of order-sensitive items. Each item consists of:
+An upstream endpoint's settings consist of a list of order-sensitive items:
 
 * A URL template, which specifies where messages send to.
 * A set of rules.
-* Authentication configurations. 
+* Authentication configurations.
 
-When the specified event happens, an item's rules are checked one by one in order. Messages will be sent to the first matching item's upstream URL.
+When an event is fired, an item's rules are checked one by one in order. Messages will be sent to the first matching item's upstream endpoint URL.
 
 ### URL template settings
 
-You can parameterize the URL to support various patterns. There are three predefined parameters:
+You can parameterize the upstream endpoint URL to support various patterns. There are three predefined parameters:
 
 |Predefined parameter|Description|
 |---------|---------|
 |{hub}| A hub is a concept of Azure SignalR Service. A hub is a unit of isolation. The scope of users and message delivery is constrained to a hub.|
-|{category}| A category can be one of the following values: <ul><li>**connections**: Connection lifetime events. It's fired when a client connection is connected or disconnected. It includes connected and disconnected events.</li><li>**messages**: Fired when clients invoke a hub method. It includes all other events, except those in the **connections** category.</li></ul>|
+|{category}| A category can be one of the following values: <ul><li>**connections**: Connection lifetime events. It's fired when a client connection is connected or disconnected. It includes connected and disconnected events.</li><li>**messages**: Fired when clients invoke a hub method. It includes all other events, except events in the **connections** category.</li></ul>|
 |{event}| For the **messages** category, an event is the target in an [invocation message](https://github.com/dotnet/aspnetcore/blob/master/src/SignalR/docs/specs/HubProtocol.md#invocation-message-encoding) that clients send. For the **connections** category, only *connected* and *disconnected* are used.|
 
-These predefined parameters can be used in the URL pattern. Parameters will be replaced with a specified value when you're evaluating the upstream URL. For example: 
+These predefined parameters can be used in the URL pattern. Parameters will be replaced with a specified value when you're evaluating the upstream endpoint URL. For example: 
 ```
 http://host.com/{hub}/api/{category}/{event}
 ```
@@ -50,70 +50,72 @@ http://host.com/chat/api/messages/broadcast
 
 ### Key Vault secret reference in URL template settings
 
-The URL of upstream is not encryption at rest. If you have any sensitive information, it's suggested to use Key Vault to save them where access control has better insurance. Basically, you can enable the managed identity of Azure SignalR Service and then grant read permission on a Key Vault instance and use Key Vault reference instead of plaintext in Upstream URL Pattern.
+The upstream endpoint URL isn't encrypted. You can secure sensitive upstream endpoints using Key Vault and access them with a managed identity. 
 
-1. Add a system-assigned identity or user-assigned identity. See [How to add managed identity in Azure Portal](./howto-use-managed-identity.md#add-a-system-assigned-identity)
+To enable managed identity in your SignalR service instance and grant it Key Vault access:
 
+1. Add a system-assigned identity or user-assigned identity. See [How to add managed identity in Azure portal](./howto-use-managed-identity.md#add-a-system-assigned-identity).
 2. Grant secret read permission for the managed identity in the Access policies in the Key Vault. See [Assign a Key Vault access policy using the Azure portal](../key-vault/general/assign-access-policy-portal.md)
 
-3. Replace your sensitive text with the below syntax in the Upstream URL Pattern:
+3. Replace your sensitive text with the below syntax in the upstream endpoint URL Pattern:
    ```
    {@Microsoft.KeyVault(SecretUri=<secret-identity>)}
-   ```
+   ``
    `<secret-identity>` is the full data-plane URI of a secret in Key Vault, optionally including a version, e.g., https://myvault.vault.azure.net/secrets/mysecret/ or https://myvault.vault.azure.net/secrets/mysecret/ec96f02080254f109c51a1f14cdb1931
    
    For example, a complete reference would look like the following:
    ```
    {@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
    ```
    
-   An upstream URL to Azure Function would look like the following:
+   An upstream endpoint URL to Azure Function would look like the following:
    ```
    https://contoso.azurewebsites.net/runtime/webhooks/signalr?code={@Microsoft.KeyVault(SecretUri=https://myvault.vault.azure.net/secrets/mysecret/)}
    ```
 
 > [!NOTE]
-> The service rereads the secret content every 30 minutes or whenever the upstream settings or managed identity changes. Try updating the Upstream settings if you'd like an immediate update when the Key Vault content is changed.
+> Every 30 minutes, or whenever the upstream endpoint settings or managed identity change, the service rereads the secret content. You can immediately trigger an update by changing the upstream endpoint settings.
 
 ### Rule settings
 
-You can set rules for *hub rules*, *category rules*, and *event rules* separately. The matching rule supports three formats. Take event rules as an example:
-- Use an asterisk(*) to match any events.
-- Use a comma (,) to join multiple events. For example, `connected, disconnected` matches the connected and disconnected events.
-- Use the full event name to match the event. For example, `connected` matches the connected event.
+You can set *hub rules*, *category rules*, and *event rules* separately. The matching rule supports three formats:
+
+* Use an asterisk (*) to match any event.
+* Use a comma (,) to join multiple events. For example, `connected, disconnected` matches the connected and disconnected events.
+* Use the full event name to match the event. For example, `connected` matches the connected event.
 
 > [!NOTE]
-> If you're using Azure Functions and [SignalR trigger](../azure-functions/functions-bindings-signalr-service-trigger.md), SignalR trigger will expose a single endpoint in the following format: `<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>`.
+> If you're using Azure Functions with [SignalR trigger](../azure-functions/functions-bindings-signalr-service-trigger.md), SignalR trigger will expose a single endpoint in the following format: `<Function_App_URL>/runtime/webhooks/signalr?code=<API_KEY>`.
 > You can just configure **URL template settings** to this url and keep **Rule settings** default. See [SignalR Service integration](../azure-functions/functions-bindings-signalr-service-trigger.md#signalr-service-integration) for details about how to find `<Function_App_URL>` and `<API_KEY>`.
 
 ### Authentication settings
 
-You can configure authentication for each upstream setting item separately. When you configure authentication, a token is set in the `Authentication` header of the upstream message. Currently, Azure SignalR Service supports the following authentication types:
+You can configure authentication for each upstream endpoint setting separately. When you configure authentication, a token is set in the `Authentication` header of the upstream message. Currently, Azure SignalR Service supports the following authentication types:
 - `None`
 - `ManagedIdentity`
 
-When you select `ManagedIdentity`, you must enable a managed identity in Azure SignalR Service in advance and optionally specify a resource. See [Managed identities for Azure SignalR Service](howto-use-managed-identity.md) for details.
+When you select `ManagedIdentity`, you must first enable a managed identity in Azure SignalR Service and optionally, specify a resource. See [Managed identities for Azure SignalR Service](howto-use-managed-identity.md) for details.
 
-## Create upstream settings via the Azure portal
+## Configure upstream endpoint settings via the Azure portal
 
 > [!NOTE]
 > Integration with App Service Environment is currently not supported.
 
 1. Go to Azure SignalR Service.
-2. Select **Settings** and switch **Service Mode** to **Serverless**. The upstream settings will appear:
-
-    :::image type="content" source="media/concept-upstream/upstream-portal.png" alt-text="Upstream settings":::
-
-3. Add URLs under **Upstream URL Pattern**. Then settings such as **Hub Rules** will show the default value.
-4. To set settings for **Hub Rules**, **Event Rules**, **Category Rules**, and **Upstream Authentication**, select the value of **Hub Rules**. A page that allows you to edit settings appears:
+1. Select **Settings**.
+1. Switch **Service Mode** to **Serverless**.
+1. Add URLs under **Upstream URL Pattern**.
+  :::image type="content" source="media/concept-upstream/upstream-portal.png" alt-text="Screenshot of AzureSignalR Service Upstream settings.":::
+1. Select **Hub Rules** to open **Upstream Settings**.
+  :::image type="content" source="media/concept-upstream/upstream-detail-portal.png" alt-text="Screenshot of Azure SignalR Upstream setting details.":::
+1. Change **Hub Rules**, **Event Rules** and **Category Rules** by entering rule value in the corresponding field.
+1. Under **Upstream Authentication** select 
+1. **Use Managed Identity**. (Ensure that you've enabled managed identity)
+1. Choose any options under **Audience in the issued token**. See [Managed identities for Azure SignalR Service](howto-use-managed-identity.md) for details.
 
-    :::image type="content" source="media/concept-upstream/upstream-detail-portal.png" alt-text="Upstream setting details":::
+## Configure upstream endpoint settings via Resource Manager template
 
-5. To set **Upstream Authentication**, make sure you've enabled a managed identity first. Then select **Use Managed Identity**. According to your needs, you can choose any options under **Auth Resource ID**. See [Managed identities for Azure SignalR Service](howto-use-managed-identity.md) for details.
-
-## Create upstream settings via Resource Manager template
-
-To create upstream settings by using an [Azure Resource Manager template](../azure-resource-manager/templates/overview.md), set the `upstream` property in the `properties` property. The following snippet shows how to set the `upstream` property for creating and updating upstream settings.
+To configure upstream endpoint settings by using an [Azure Resource Manager template](../azure-resource-manager/templates/overview.md), set the `upstream` property in the `properties` property. The following snippet shows how to set the `upstream` property for creating and updating upstream endpoint settings.
 
 ```JSON
 {
@@ -186,8 +188,9 @@ Content-Type: `application/json` or `application/x-msgpack`
 
 ### Signature
 
-The service will calculate SHA256 code for the `X-ASRS-Connection-Id` value by using both the primary access key and the secondary access key as the `HMAC` key. The service will set it in the `X-ASRS-Signature` header when making HTTP requests to upstream:
-```
+The service will calculate SHA256 code for the `X-ASRS-Connection-Id` value by using both the primary access key and the secondary access key as the `HMAC` key. The service will set it in the `X-ASRS-Signature` header when making HTTP requests to an upstream endpoint:
+
+```text
 Hex_encoded(HMAC_SHA256(accessKey, connection-id))
 ```
 

articles/azure-signalr/howto-use-managed-identity.md

@@ -64,18 +64,18 @@ Azure SignalR Service is a fully managed service.  It uses a managed identity to
 
 ### Enable managed identity authentication in upstream settings
 
-Once you've added a [system-assigned identity](#add-a-system-assigned-identity) or [user-assigned identity](#add-a-user-assigned-identity) to your SignalR instance, you can enable managed identity authentication in the upstream settings.
+Once you've added a [system-assigned identity](#add-a-system-assigned-identity) or [user-assigned identity](#add-a-user-assigned-identity) to your SignalR instance, you can enable managed identity authentication in the upstream endpoint settings.
 
 1. Browse to your SignalR instance.
 1. Select **Settings** from the menu.
 1. Select the **Serverless** service mode.
-1. Enter the upstream URL pattern in the **Add an upstream URL pattern** text box.  See [URL template settings](concept-upstream.md#url-template-settings)
-1. Select Add one Upstream Setting and select any asterisk to get into a detailed page as shown below.
-    :::image type="content" source="media/signalr-howto-use-managed-identity/pre-msi-settings.png" alt-text="pre-msi-setting":::
+1. Enter the upstream endpoint URL pattern in the **Add an upstream URL pattern** text box.  See [URL template settings](concept-upstream.md#url-template-settings)
+1. Select Add one Upstream Setting and select any asterisk go to **Upstream Settings**.
+    :::image type="content" source="media/signalr-howto-use-managed-identity/pre-msi-settings.png" alt-text="Screenshot of Azure SignalR service Settings.":::
 
-1. Configure your upstream settings.  
+1. Configure your upstream endpoint settings.  
 
-    :::image type="content" source="media/signalr-howto-use-managed-identity/msi-settings.png" alt-text="msi-setting":::
+    :::image type="content" source="media/signalr-howto-use-managed-identity/msi-settings.png" alt-text="Screenshot of Azure SignalR service Upstream settings.":::
 
 1. In the managed identity authentication settings, for **Resource**, you can specify the target resource. The resource will become an `aud` claim in the obtained access token, which can be used as a part of validation in your upstream endpoints. The resource can be one of the following formats:
     - Empty
@@ -101,7 +101,9 @@ Libraries and code samples that show how to handle token validation are availabl
 You can easily set access validation for a Function App without code changes using the Azure portal.
 
 1. Go to the Function App in the Azure portal.
-1. In the **Authentication** page, select **Add identity provider**
+1. Select **Authentication** from the menu.
+1. Select **Add identity provider**.
+1. In the **Basics** tab, select **Microsoft** from the **Identity provider** dropdown.
 1. Select **Log in with Azure Active Directory** in **Action to take when request is not authenticated**.
 1. Select **Microsoft** in the identity provider dropdown. The option to create a new registration is selected by default. You can change the name of the registration. For more information on enabling Azure AD provider, see [Configure your App Service or Azure Functions app to use Azure AD login](../app-service/configure-authentication-provider-aad.md)
     :::image type="content" source="media/signalr-howto-use-managed-identity/function-aad.png" alt-text="Function Aad":::

articles/azure-signalr/index.yml

@@ -102,7 +102,7 @@ landingContent:
         links:
           - text: Develop and configure with Azure Functions
             url: signalr-concept-serverless-development-config.md
-          - text: Upstream settings
+          - text: Upstream endpoints
             url: concept-upstream.md
       - linkListType: reference
         links:

articles/azure-signalr/media/concept-upstream/upstream-detail-portal.png

@@ -49,7 +49,7 @@ Use the `SignalRTrigger` binding to handle messages sent from SignalR Service. Y
 
 For more information, see the [SignalR Service trigger binding reference](../azure-functions/functions-bindings-signalr-service-trigger.md).
 
-You also need to configure your function endpoint as an upstream so that service will trigger the function when there's message from a client. For more information about how to configure upstream, see [Upstream settings in Azure SignalR Service](concept-upstream.md).
+You also need to configure your function endpoint as an upstream endpoint so that service will trigger the function when there's message from a client. For more information about how to configure upstream endpoints, see [Upstream endpoints](concept-upstream.md).
 
 > [!NOTE]
 > SignalR Service doesn't support the `StreamInvocation` message from a client in Serverless Mode.