Add security considerations and how-it-works documentation; update FAQ

Author: fboucher

doc/faq.md

@@ -7,7 +7,8 @@
 - [How to deploy your AzUrlShortener](./how-to-deploy.md)
 - [How to run AzUrlShortener locally](#how-to-run-azurlshortener-locally)
 - [How to update/ redeploy AzUrlShortener](#update-redeploy-azurlshortener)
-
+- [How does it work?](./how-it-works.md)
+- [Security Considerations](./security-considerations.md)
 
 
 ## How to run AzUrlShortener locally

doc/how-it-works.md

@@ -0,0 +1,39 @@
+How It Works
+============
+
+The backend is using Azure Functions and Azure Table Storable this page will explains how they work together in this tool.
+
+![Global Diagram](../images/global_diagram_idea_v3b.jpg)
+
+## Azure Functions
+
+Azure Functions were the perfect match for this project because when you use a dynamic plan you are charged only when the function is running. In our case, it's only a few seconds at the time. To know more read [Azure Function Pricing](https://azure.microsoft.com/en-us/pricing/details/functions/)
+
+### Function: UrlRedirect
+
+This function returns a HTTP Redirect to the URL. You can call it directly doing an HTTP request of type POST or GET passing the vanity at the end of the URL. The Azure Function Proxy will call Function passing the parameter.
+
+For example, if the domain is *c5m.ca* and the vanity is "project", the request `c5m.ca/2w` will call "UrlRedirect/{shortUrl}" where `shortUrl` is equal to "project". end the result will be a redirect to the long URL save in the storage.
+
+Every time the Azure Function is called it will increment the click count and save the timestamp when this call appends.
+
+## Azure Table Storage
+
+The [Azure table storage](https://docs.microsoft.com/en-us/azure/storage/tables/) are the data store in this project. They are a very convenient service to keep structured NoSQL data in the cloud. They are also typically lower in cost than traditional SQL for similar volumes of data.
+
+You can explore the Azure Table storage from Azure portal or using the [Azure Storage Explorer](https://docs.microsoft.com/en-us/azure/vs-azure-tools-storage-manage-with-storage-explorer?tabs=windows#overview) it's a nice free tool that is available on all platforms (MacOS, Linux, Windows).
+
+There are two tables that will be automatically created at the first call.
+
+### Table: ClickStats
+
+The ClickStats table get a new entry at every call of the Azure Function **UrlRedirect** with the Datetime value.
+
+
+### Table: UrlDetails
+
+The UrlDetails table has the information about all the URLs created. The Vanity, URL, and number of clicks.
+
+## Security Considerations
+
+Review [Security Considerations](./security-considerations.md) and choose and implement an appropriate authorization approach.

doc/security-considerations.md

@@ -0,0 +1,20 @@
+# Security Responsibilities
+
+This is open-source software and delivered as a Proof-of-concept. Please consider which security approaches is appropriate for your use case.
+
+## Current Implementation 
+
+The [TinyBlazorAdmin](../src/Cloud5mins.ShortenerTools.TinyBlazorAdmin/) is secured using the built-in authentication feature of Azure Container Apps (ACA) is a simple and powerful way to add authentication your applications with minimal effort. Here are some key points to remember:
+
+- You don't need to change the existing app code to add this authentication feature.
+- This built-in authentication feature of ACA protects your entire application, not individual pages.
+
+For more details about the built-in authentication feature of ACA, see [Authentication and authorization in Azure Container Apps](https://learn.microsoft.com/azure/container-apps/authentication).
+
+## Basic Security Approaches
+
+Using Azure Container Apps (ACA), the API container will only be accessible from the TinyBlazorAdmin and won't be exposed to the Internet. As a bonus, since TinyBlazorAdmin and the API are now running inside containers, you could also decide to run them locally.
+
+The storage access got also a security upgrade. Instead of using a connection string, I will be using a Managed Identity to access the Azure Storage Table. This is a much more secure way to access Azure resources, and thanks to .NET Aspire, it is also very easy to implement.
+
+For more details about Security read the [SECURITY.md](../SECURITY.md) file.