Upstream endpoints

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.

Upstream endpoint settings

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.

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 upstream endpoint URL to support various patterns. There are three predefined parameters:

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}

When a client connection in the "chat" hub is connected, a message will be sent to this URL:

http://host.com/chat/api/connections/connected

When a client in the "chat" hub invokes the hub method broadcast, a message will be sent to this URL:

http://host.com/chat/api/messages/broadcast

Key Vault secret reference in URL template settings

The upstream endpoint URL isn't encrypted. You can secure sensitive upstream endpoints using Key Vault and access them with a managed 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.

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

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 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/)}
   

Rule settings

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.

Authentication settings

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 first enable a managed identity in Azure SignalR Service and optionally, specify a resource. See Managed identities for Azure SignalR Service for details.

Configure upstream endpoint settings via the Azure portal

1. Go to Azure SignalR Service.
2. Select Settings.
3. Switch Service Mode to Serverless.
4. Add URLs under Upstream URL Pattern.
5. Select Hub Rules to open Upstream Settings.
6. Change Hub Rules, Event Rules and Category Rules by entering rule value in the corresponding field.
7. Under Upstream Authentication select
8. Use Managed Identity. (Ensure that you've enabled managed identity)
9. Choose any options under Audience in the issued token. See Managed identities for Azure SignalR Service for details.

Configure upstream endpoint settings via Resource Manager template

To configure upstream endpoint settings by using an Azure Resource Manager template, 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.

{
  "properties": {
    "upstream": {
      "templates": [
        {
          "UrlTemplate": "http://host.com/{hub}/api/{category}/{event}",
          "EventPattern": "*",
          "HubPattern": "*",
          "CategoryPattern": "*",
          "Auth": {
            "Type": "ManagedIdentity",
            "ManagedIdentity": {
              "Resource": "<resource>"
            }
          }
        }
      ]
    }
  }
}

Serverless protocols

Azure SignalR Service sends messages to endpoints that follow the following protocols. You can use SignalR Service trigger binding with Function App, which handles these protocols for you.

Method

POST

Request header

Request body

Connected

Content-Type: application/json

Disconnected

Content-Type: application/json

Invocation message

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 an upstream endpoint:

Hex_encoded(HMAC_SHA256(accessKey, connection-id))

Next steps

• Managed identities for Azure SignalR Service
• Azure Functions development and configuration with Azure SignalR Service
• Handle messages from SignalR Service (Trigger binding)
• SignalR Service Trigger binding sample