Add Sample Documentation

Samples/PublicSamples/RecordingBot/README.md

@@ -1,4 +1,4 @@
-> **Note**  
+> [!NOTE]  
 > Public Samples are provided by developers from the Microsoft Graph community.  
 > Public Samples are not official Microsoft Communication samples, and not supported by the Microsoft Communication engineering team. It is recommended that you contact the sample owner before using code from Public Samples in production systems.
 
@@ -17,16 +17,13 @@ Lead maintainer: [@InDieTasten](https://github.com/InDieTasten)
 **Fork for issues and contributions:**  
 [LM-Development/aks-sample](https://github.com/LM-Development/aks-sample)
 
-
 # Introduction
 
 This sample allows you to build, deploy and test a compliance recording bot running on Azure Kubernetes Service and is currently the only sample demonstrating a basis for zero-downtime deployments and horizontal scaling ability.
 
 The unique purpose of this sample is to demonstrate how to run production grade bots. The bot implementation can easily be changed to fit other use cases other than compliance recording.
 
-### Contents
-
-Outline the file contents of the repository. It helps users navigate the codebase, build configuration and any related assets.
+## Contents
 
 | File/folder       | Description                                |
 |-------------------|--------------------------------------------|
@@ -42,18 +39,14 @@ Outline the file contents of the repository. It helps users navigate the codebas
 ## Getting Started
 
 The easiest way to grasp the basics surrounding compliance bots is to read up on the following documentation topics:
-> 🚩 TODO: 1. Understanding App-Hosted Media Bot Networking  
 
-> 🚩 TODO: 2. Understanding Entra and Graph Calling Permissions  
-
-> 🚩 TODO: 3. Understanding Compliance Recording Policies
+- [High Level Overview over the Infrastructure for the Recording Bot](./docs/explanations/recording-bot-overview.md)
+- [Bot Service - Entra Id and Microsoft Graph API Calling Permissions](./docs/explanations/recording-bot-permission.md)
+- [Compliance Recording Policies](./docs/explanations/recording-bot-policy.md)
 
 ### Deploy
 
-> 🚩 TODO: Prerequisites
-
-> 🚩 TODO: AKS, bot registration, permissions, docker, helm, compliance policies
-
+[Deploy the recording bot sample to AKS with the tutorial](./docs/tutorials/deploy-tutorial.md), to get your own recording bot up and running.
 
 ### Local Run
 
@@ -71,7 +64,6 @@ The easiest way to grasp the basics surrounding compliance bots is to read up on
 
 > For this sample related questions, please open an issue in the [issue tracker](https://github.com/LM-Development/aks-sample/issues) of the fork repository.
 
-
 ---
 
 # 🚩 TODO: Transfer applicable details into above todos or other docs pages
@@ -122,7 +114,7 @@ The easiest way to grasp the basics surrounding compliance bots is to read up on
     AzureSettings__WAVQuality=100 ## from 0 to 100%, when omitted, by default is 100%
     ```
 
->Note: You don't need to create another `.env` file for your Testing project. It's there for the CI/CD build pipeline.
+>Note: You do not need to create another `.env` file for your Testing project. It is there for the CI/CD build pipeline.
 
 6. Optional - Including publishing of Bot Events with Azure Event Grid
    * Create an [Event Grid custom topic in Azure Event Grid](https://docs.microsoft.com/en-us/azure/event-grid/scripts/event-grid-cli-create-custom-topic) in the CLI or Azure portal (to receive events) with the default `TOPIC_NAME` of `recordingbotevents`.
@@ -150,7 +142,7 @@ If you are running the project locally, you will need Ngrok running to forward t
 
 1. Create a new file called `ngrok.yaml` in the [scripts](scripts) folder.
 2. Copy the contents of [ngrok.yaml-template](scripts/ngrok.yaml-template) over to `ngrok.yaml`.
-3. Update `ngrok.yaml` with 
+3. Update `ngrok.yaml` with
     ```
     <AUTH_TOKEN>: Your Ngrok authentication token.
 
@@ -164,7 +156,7 @@ If you are running the project locally, you will need Ngrok running to forward t
     For example 8445
     ```
 
-Once you've done that, run [runngrok.bat](scripts/runngrok.bat) in command prompt and leave it running.
+Once you have done that, run [runngrok.bat](scripts/runngrok.bat) in command prompt and leave it running.
 
 ### Visual Studio
 
@@ -211,7 +203,7 @@ To build the image, make sure Docker is running and is set to `Windows Container
 
 To do this, right click on Docker in your system tray and click `Switch to Windows containers...`. Wait for Docker to restart before continuing.
 
-1. To build the container, open a new powershell terminal and make sure you've changed directories to the root of this repository. If you are, run the following command:
+1. To build the container, open a new powershell terminal and make sure you have changed directories to the root of this repository. If you are, run the following command:
 
     ```powershell
     docker build `
@@ -222,7 +214,7 @@ To do this, right click on Docker in your system tray and click `Switch to Windo
         -t [TAG]
     ```
 
-2. Before we can run the project, you need to extract your `certificate.pfx` you generated in [Setting up URL ACL and Certificate Bindings](docs/setup/certificate.md) into individual `.key` and `.cert` files. You'll need to make sure you have [OpenSSL](https://chocolatey.org/packages/OpenSSL.Light) installed. Currently [entrypount.cmd](scripts/entrypoint.cmd) does not check if a `certificate.pfx` exists and expects it has to generate it and add it to the container's certificate store.
+2. Before we can run the project, you need to extract your `certificate.pfx` you generated in [Setting up URL ACL and Certificate Bindings](docs/setup/certificate.md) into individual `.key` and `.cert` files. You will need to make sure you have [OpenSSL](https://chocolatey.org/packages/OpenSSL.Light) installed. Currently [entrypount.cmd](scripts/entrypoint.cmd) does not check if a `certificate.pfx` exists and expects it has to generate it and add it to the container's certificate store.
 
     To extract your `certificate.pfx`, run the following command in powershell:
 
@@ -251,15 +243,15 @@ To do this, right click on Docker in your system tray and click `Switch to Windo
     - Make sure you replace `CERTIFICATE_PATH` with the folder location of your `tls.cert` and `tls.key`.
     - The bot needs at least 2 CPU cores for it to run. We specify this with `--cpus 2.5`.
 
-**Note**: You can also join the docker later if you'd like to retrieve the wav files in the docker container itself by running this command:
+**Note**: You can also join the docker later if you would like to retrieve the wav files in the docker container itself by running this command:
 
 ```powershell
 docker exec -it <container_id> powershell
 ```
 
 **IMPORTANT**:
 
-5. If you're attaching to the existing docker instance, make sure to run `.\entrypoint.cmd`. You'll see a bunch of activity in your console but once you see `RecordingBot: running`, you're good to go. Make sure you have Ngrok running before trying to interact with the bot through teams.
+5. If you are attaching to the existing docker instance, make sure to run `.\entrypoint.cmd`. You will see a bunch of activity in your console but once you see `RecordingBot: running`, you are good to go. Make sure you have Ngrok running before trying to interact with the bot through teams.
 
 ## Key concepts
 
@@ -269,7 +261,7 @@ Provide users with more context on the tools and services used in the sample. Ex
 
 This project welcomes contributions and suggestions.  Most contributions require you to agree to a
 Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+the rights to use your contribution. For details, visit <https://cla.opensource.microsoft.com>.
 
 When you submit a pull request, a CLA bot will automatically determine whether you need to provide
 a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions

Samples/PublicSamples/RecordingBot/docs/explanations/recording-bot-overview.md

@@ -0,0 +1,72 @@
+# High Level Overview
+
+![Image 1](../images/Overview.svg)
+
+As seen in the image, Microsoft Teams clients communicate with the Micorsoft Teams platform, which
+communicates with the bot recording application via different channels. The Microsoft Teams platform
+gets a URL pointing to the notifications endpoint of the bot recording application from a bot service.
+
+The following list represents the default flow of a one to one call or meeting, initiated by a
+Microsoft Teams user.
+
+1. The users Microsoft Teams client connects to the Microsoft Teams platform.
+2. The Microsoft Teams platform evaluates the compliance recording policies.
+
+    - If the user is under a policy:
+
+3. The Microsoft Teams platform loads the HTTPS notification URL from the corresponding bot service.
+4. The Microsoft Teams platform creates a call (an entity) on the Graph Communications API for the
+    bot recording application, with destination to the users call and metadata of the users call.
+5. The call is sent to the notification URL of the bot recording application.
+
+> [!IMPORTANT]  
+> The notification URL must be HTTPS and the certificate used must be signed by a valid authority.
+
+When the bot recording application receives the notification with the new call from the Microsoft
+Teams platform, the application should answer the call via the Graph Communications API. The API
+request to answer must contain some configuration e.g. the TCP endpoint of the media processor of
+the bot or a new notification URL for further notifications regarding the call. The recording bot
+application receives notifications via the aforementioned URL for users joining, leaving, muting,
+starting screen shares and more.
+
+After the bot recording application answered and accepted a call, the Microsoft Teams platform
+opens a connection on the provided TCP endpoint. After an initial handshake for authorization
+and encryption, metadata and media events are transferred via the TCP connection.
+
+> [!IMPORTANT]  
+> The TCP endpoint also requires a certificate signed by a valid authority. The Certificate for the
+> HTTPS endpoint and the TCP endpoint **can** be the same.
+
+## Graph Communications SDK
+
+The overhead of the TCP endpoints is completly managed by the Graph Communications SDK, but the
+HTTPS endpoints for notifications must be custom implemented by the bot recording application.
+ASP.NET Core can be used. After a HTTP request is authorized and notifications are parsed from the
+request, the notifications should be forwarded to the SDK. The SDK will process notifications and
+fire events based on these notifications. The event handlers can implement business logic. An
+event handler that, for example, triggers when a new call notification was received, should be used
+for answering calls. Before answering, business logic can decide whether the call should be
+accepted. Such an event handler should use the `answer` method of the SDK with the desired
+configuration to accept a call. The configuration specifies how many video sockets should be
+created, if the notification url changes and more. In the case that a call should not be accepted,
+a `reject` method of the SDK can be used.
+
+As the Microsoft Graph Communications SDK takes care of a lot of overhead and endpoint handling,
+the SDK also needs to be configured correctly with:
+
+- a valid certificate as part of the TCP endpoint configuration
+- DNS name
+- port(s)
+- Notification Endpoint configuration
+- Graph Communications API connection configuration
+
+The SDK also needs an implementation of an authorization handler for:
+
+- API calls to the Graph Communications API
+- validating incoming requests (within the initial TCP handshake of the SDK)
+- (optionally) validating HTTP requests on the custom implemented notification endpoint
+
+> [!NOTE]  
+> The application requires some application permissions on an app registration that is bound to a
+> bot service to be able to answer calls and access media from calls, see the
+> [Application Permissions Page](./recording-bot-permission.md) for reference.

Samples/PublicSamples/RecordingBot/docs/explanations/recording-bot-permission.md

@@ -0,0 +1,39 @@
+# Bot Service - Microsoft Entra Id and Micosoft Graph API Calling Permission
+
+An Azure bot service can be created with an existing app registration in the Microsoft Entra Id or
+can create a new app registration in the Microsoft Entra Id on creation. The app registration can
+be a single tenant app registration or a multi tenant app registration, also see
+["Tenancy in Microsoft Entra ID" documentaion](https://learn.microsoft.com/entra/identity-platform/single-and-multi-tenant-apps). Either way it is required that the Microsoft Entra
+ Id app registration and the bot service are linked.
+
+Also the app registration must have some application permissions exposed by the Microsoft Graph API
+that allows the recording application to join calls and access the media streams. The following
+Microsoft Graph API application permissions are relevant for the recording bot:
+
+|  permission  |  description  |
+| ------------ | ------------- |
+| [Calls.Initiate.All](https://learn.microsoft.com/graph/permissions-reference#callsinitiateall) | Allows the app to place outbound calls to a single user and transfer calls to users in your organization's directory, without a signed-in user. |
+| [Calls.InitiateGroupCall.All](https://learn.microsoft.com/graph/permissions-reference#callsinitiategroupcallall) | Allows the app to place outbound calls to multiple users and add participants to meetings in your organization, without a signed-in user. |
+| [Calls.JoinGroupCall.All](https://learn.microsoft.com/graph/permissions-reference#callsjoingroupcallall) | Allows the app to join group calls and scheduled meetings in your organization, without a signed-in user. The app will be joined with the privileges of a directory user to meetings in your tenant. |
+| [Calls.JoinGroupCallasGuest.All](https://learn.microsoft.com/graph/permissions-reference#callsjoingroupcallasguestall) | Allows the app to anonymously join group calls and scheduled meetings in your organization, without a signed-in user. The app will be joined as a guest to meetings in your tenant. |
+| [Calls.AccessMedia.All](https://learn.microsoft.com/graph/permissions-reference#callsaccessmediaall) | Allows the app to get direct access to participant media streams in a call, without a signed-in user. |
+
+Not all of them are necessary for a compliance recording bots. A compliance recording only requires:
+
+- Calls.AccessMedia.All
+- Calls.JoinGroupCall.All
+- Calls.JoinGroupCallAsGuest.All
+
+> [!IMPORTANT]  
+> After configuring the application permissions it is required that a Microsoft Entra Id
+> administrator grants the permissions. This also applies for any time the application permissions
+> are changed. Changes made to the application permissions of an app registration will not take
+> effect until a Microsoft Entra Id administarator has consented to them.
+
+It is possible for administrators to grant the application permissions in the [Azure portal](https://portal.azure.com),
+but often a better option is to provide a sign-up experience for administrators by using the
+Microsoft Entra Id `/adminconsent` endpoint, see [instructions on constructing an Admin Consent URL](https://learn.microsoft.com/entra/identity-platform/v2-admin-consent).
+
+> [!Note]  
+> Application permissions of a multi tenant app registration must be granted by an administrator of
+> each targeted Microsoft Entra Id tenant.

Samples/PublicSamples/RecordingBot/docs/explanations/recording-bot-policy.md

@@ -0,0 +1,55 @@
+# Compliance Recording Policies
+
+> [!TIP]  
+> Also read the [How To Recording Policies Guide](../guides/policy.md)
+
+Compliance recording policies are the connection between Microsoft Teams users doing calls and bot
+recording application ready to record. If a Microsoft Teams user tries to do a call, the Microsoft
+Teams platform evaluates the compliance recording policies of the user. When policies are assigned
+to a user or to a group of the user the policy is further evaluated. Policies always have to be set
+up for each Microsoft Entra Id tenant induvidualy.
+
+Policies itself are complex to setup and allow for a lot of options. It is possible to configure
+the policy to invite multiple recording bots for resilience, or that it is allowed for users to do
+calls without a recording bot present.
+
+Recording policies are made of 3 parts:
+
+- [Recording Policy](#recording-policies)
+- [Recording Application](#recording-applications)
+- [Application Instance](#application-instances)
+
+When the Microsoft Teams platform finds a recording policy assigned to an user, it further
+evaluates the recording application and loads the app registration from the corresponding
+application instance. The Microsoft Teams platform then gets the notification URL from the bot
+service that is linked to the app registration and sends the notification to the recording bot via
+the notification URL in the bot service.
+
+## Recording Policies
+
+Recording policies are managable instances that can be assigend to users, groups of users or to a
+whole tenant (all users of a tenant). Policies contain a recording application.
+
+## Recording Applications
+
+Recording applications define how the Microsoft Teams platform should behave with the policy. A
+recording application can define, that the recording bot has to be present before the user is
+allowed to establish a connection to the call, that users disconnect if the bot leaves or rejects a
+call, or that an audio message should be played if the recording bot sets the recording status to
+recording. A recording application can also define a paired recording application that is also
+invited. This can, for example, be used as backup to raise resilience.
+
+## Application Instances
+
+An application instance is the connection between the recording application for the policy and the
+app registration of the bot implementation. The application instance creates a Microsoft Entra Id
+resource that is linked to the app registration, also in Entra Id. The app registration and the
+application instance do not have to be in the same Entra Id tenant. This is especially interesting
+for multi tenant recording bot implementations as it allows the hosting tenant to configure things
+like permissions and the notification URL and the consumer tenants to define the behaviour of the
+recording policy.
+
+An application instance is a Microsoft Entra Id resource similar to a user. Application instances
+also require user principal names to be set. When the Microsoft Teams platform evaluates the
+recording policies, an application instance delivers the app registration that is linked to a bot
+service that contains the notification url.