Updates to setup and documentation due to Key Vault and other changes

Author: joelhulen

documentation/api-management.md

@@ -1,6 +1,7 @@
 # Gateway using API Management
 
-- [Next steps](#next-steps)
+- [Gateway using API Management](#gateway-using-api-management)
+  - [Next steps](#next-steps)
 
 There are many benefits to using an API manager. In the case the Rideshare solution, there are really four major benefits:
 
@@ -112,7 +113,7 @@ public static async Task<IActionResult> GetDrivers([HttpTrigger(AuthorizationLev
 
 4. **Rate Limiting**: the API manager can be configured to rate limit APIs based on IP origin, access, etc. This can be useful to prevent DOD attacks or provide different tiers of access based on users.
 
-**Please note** that, in the case of Azure Functions, while the APIs are front-ended with an API manager (and hence shielded, protected, and rate limited), the APIs are still publicly available. This means that a DDOS attack or other attacks can still happen against the bare APIs if someone discovers them in the wild.
+**Please note** that, in the case of Azure Functions, while the APIs are front-ended with an API manager (and hence shielded, protected, and rate limited), the APIs are still publicly available. This means that a DDOS attack or other attacks can still happen against the bare APIs if someone discovers them in the wild. However, you can restrict access to your Function Apps by [only allowing access to your API Management's static IP](https://docs.microsoft.com/azure/app-service/app-service-ip-restrictions) address. When you do this, only traffic that flows through API Management will be able to access your functions.
 
 ## Next steps
 

documentation/architecture-overview.md

@@ -1,8 +1,9 @@
 # Architecture overview
 
-- [Macro architecture](#macro-architecture)
-- [Data flow](#data-flow)
-- [Next steps](#next-steps)
+- [Architecture overview](#architecture-overview)
+  - [Macro architecture](#macro-architecture)
+  - [Data flow](#data-flow)
+  - [Next steps](#next-steps)
 
 ## Macro architecture
 
@@ -12,14 +13,15 @@ Relecloud decided to use the following macro architecture in their RideShare sol
 
 The architecture major building blocks are:
 
-| Component             | Technology                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                |
-| --------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| RideShare Web App     | Vue.js SPA                                                                                          | A multi-purpose, single-page application web app that allows users to sign up and sign in against a B2C Active Directory instance. Users have different levels and permissions. For example, passenger users can request rides and receive real-time notifications of ride status. Executive users, on the other hand, can view top-level reports that reveal rides and system performance |
-| API Manager           | [Azure API Manager](https://docs.microsoft.com/azure/api-management/)                               | An API gateway that acts as a front-end to the solution APIs. Among many other benefits, the API management service provides RideShare APIs with security verification, usage telemetry, documentation and rate limiting.                                                                                                                                                                  |
-| RideShare APIs        | C# [Azure Functions](https://azure.microsoft.com/services/functions/)                               | Three Function Apps are deployed to serve RideShare's APIs: Drivers, Trips and Passengers. These APIs are exposed to the Web App applications via the API manager and provide CRUD operations for each of RideShare entities                                                                                                                                                               |
-| Durable Orchestrators | C# [Durable Functions](https://docs.microsoft.com/azure/azure-functions/durable-functions-overview) | Trip Manager, Monitor and Demo orchestrators are deployed to manage the trip and provide real-time status updates. The orchestrators are launched for the duration of the trip and they perform management and monitoring functions as will be explained in more [details](#durable-orchestrators) later. In essence, these orchestrators make up the heart of the solution.               |
-| Event Emitter         | [Event Grid Topic](https://docs.microsoft.com/azure/event-grid/overview)                            | A custom topic used to externalize trips as they go through the different stages.                                                                                                                                                                                                                                                                                                          |
-| Event Subscribers     | Functions & Logic Apps                                                                              | Several Event Grid topic subscribers listen to the Event Grid topic events to provide multi-process capability of an externalized trip                                                                                                                                                                                                                                                     |
+| Component             | Technology                                                                                          | Description                                                                                                                                                                                                                                                                                                                                                                                 |
+| --------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| RideShare Web App     | Vue.js SPA                                                                                          | A multi-purpose, single-page application web app that allows users to sign up and sign in against a B2C Active Directory instance. Users have different levels and permissions. For example, passenger users can request rides and receive real-time notifications of ride status. Executive users, on the other hand, can view top-level reports that reveal rides and system performance. |
+| API Manager           | [Azure API Manager](https://docs.microsoft.com/azure/api-management/)                               | An API gateway that acts as a front-end to the solution APIs. Among many other benefits, the API management service provides RideShare APIs with security verification, usage telemetry, documentation and rate limiting.                                                                                                                                                                   |
+| RideShare APIs        | C# [Azure Functions](https://azure.microsoft.com/services/functions/)                               | Three Function Apps are deployed to serve RideShare's APIs: Drivers, Trips and Passengers. These APIs are exposed to the Web App applications via the API manager and provide CRUD operations for each of RideShare entities.                                                                                                                                                               |
+| Durable Orchestrators | C# [Durable Functions](https://docs.microsoft.com/azure/azure-functions/durable-functions-overview) | Trip Manager, Monitor and Demo orchestrators are deployed to manage the trip and provide real-time status updates. The orchestrators are launched for the duration of the trip and they perform management and monitoring functions as will be explained in more [details](#durable-orchestrators) later. In essence, these orchestrators make up the heart of the solution.                |
+| Event Emitter         | [Event Grid Topic](https://docs.microsoft.com/azure/event-grid/overview)                            | A custom topic used to externalize trips as they go through the different stages.                                                                                                                                                                                                                                                                                                           |
+| Event Subscribers     | Functions & Logic Apps                                                                              | Several Event Grid topic subscribers listen to the Event Grid topic events to provide multi-process capability of an externalized trip.                                                                                                                                                                                                                                                     |
+| Key Vault             | [Azure Key Vault](https://docs.microsoft.com/azure/key-vault/key-vault-overview)                    | All secrets, such as database connection strings and keys are securely stored in Azure Key Vault. This prevents accidental leakage of sensitive values and the same keys can be easily shared by multiple services.                                                                                                                                                                         |
 
 The following are the Event Grid Subscribers:
 

documentation/media/apim-api-creation.png

@@ -1,12 +1,14 @@
 # Services intercommunication using Event Grid
 
-- [Logic App handler](#logic-app-handler)
-- [SignalR handler](#signalr-handler)
-  - [DOTNET SignalR client](#dotnet-signalr-client)
-  - [JavaScript SignalR client](#javascript-signalr-client)
-- [Power BI handler](#power-bi-handler)
-- [Trip Archiver handler](#trip-archiver-handler)
-- [Next steps](#next-steps)
+- [Services intercommunication using Event Grid](#services-intercommunication-using-event-grid)
+  - [Event Grid](#event-grid)
+        - [Logic App handler](#logic-app-handler)
+        - [SignalR handler](#signalr-handler)
+          - [DOTNET SignalR client](#dotnet-signalr-client)
+          - [JavaScript SignalR client](#javascript-signalr-client)
+        - [Power BI handler](#power-bi-handler)
+        - [Trip Archiver handler](#trip-archiver-handler)
+  - [Next steps](#next-steps)
 
 ## Event Grid
 
@@ -149,6 +151,7 @@ public static async Task ProcessTripExternalizations2SignalR([EventGridTrigger]
         log.LogInformation($"ProcessTripExternalizations2SignalR firing SignalR `{clientMethod}` client method!");
         await signalRMessages.AddAsync(new SignalRMessage()
         {
+            UserId = trip.Passenger.Code,
             Target = clientMethod,
             Arguments = new object[] { trip}
         });
@@ -164,7 +167,7 @@ public static async Task ProcessTripExternalizations2SignalR([EventGridTrigger]
 
 **Please note** that, in the reference implementation, `EVGH_` is added to the function name that handles an Event Grid event i.e. `EVGH_TripExternalizations2SignalR`.
 
-When an Event Grid Topic event arrives at the SignalR processor, it extracts the `TripItem` from the event data and calls different client methods based on the event subject to notify SignalR clients, in real-time, of trip state changes.
+When an Event Grid Topic event arrives at the SignalR processor, it extracts the `TripItem` from the event data and calls different client methods based on the event subject to notify SignalR clients, in real-time, of trip state changes. The `UserId` value tells the SignalR Service which client should receive the message so it will not be sent to every connected user.
 
 In this reference implementation, the SignalR client is the Web App SPA. But a Xamarin Mobile App or .NET client can also receive SignalR messages. When a client receives a SignalR message, they change the trip state so passengers and drivers become aware of the latest trip status.
 
@@ -235,12 +238,12 @@ Console.WriteLine("SignalR client started....waiting for messages from server. T
 Console.ReadLine();
 ```
 
-Where `GetSignalRInfo` retrieves via a `Get` operation the `SignalR Info` from a Function also defined in the `Trips Function App`:
+Where `GetSignalRInfo` retrieves via a `Get` operation the `SignalR Info` from a Function also defined in the `Trips Function App`. Notice that the `SignalRConnectionInfo` binding contains a `HubName` parameter to define the SignalR hub, and a `UserId` parameter that defines the request header value used to retrieve the requestor's User ID value. When you pass a User ID to this method, then you are able to target messages just to that user so it doesn't appear for all users. This is useful when sending trip-related messages, as you would not want those to display on every user's screen.
 
 ```csharp
 [FunctionName("GetSignalRInfo")]
 public static IActionResult GetSignalRInfo([HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = "signalrinfo")] HttpRequest req,
-    [SignalRConnectionInfo(HubName = "trips")] AzureSignalRConnectionInfo info,
+    [SignalRConnectionInfo(HubName = "trips", UserId = "{headers.x-ms-signalr-userid}")] AzureSignalRConnectionInfo info,
     ILogger log)
 {
     log.LogInformation("GetSignalRInfo triggered....");