Merge pull request #442 from EldenCloud/feature_managed_Identities

Added new feature to integrate azure services using managed identities

.gitignore

@@ -35,3 +35,4 @@ next-env.d.ts
 .azure/
 infra/aad_setup.sh
 .vscode
+infra/main.parameters.example.json

README.md

@@ -1,36 +1,46 @@
+# What's new - January 2025
+
+A new year brings some much requested feature updates to one of our most popular AI chat repos!
+
+- **[Managed Identity-based security](/docs/9-managed-identities.md)**. This uses Azure's underlying RBAC and removes (almost) all keys/secrets.
+- `appreg_setup.ps1` helper script to **[create the App Registration for you](/docs/3-add-identity.md#entra-id-authentication-provider)** in Entra ID (if you have the permissions). Less copypasta means happier devs 🥰
+
 # Unleash the Power of Azure OpenAI
 
 1. [Introduction](#introduction)
-1. [Solution Overview](/docs/1-introduction.md)
-1. [Deploy to Azure](#deploy-to-azure)
-1. [Run from your local machine](/docs/3-run-locally.md)
-1. [Deploy to Azure with GitHub Actions](/docs/4-deploy-to-azure.md)
-1. [Add identity provider](/docs/5-add-identity.md)
-1. [Chatting with your file](/docs/6-chat-over-file.md)
-1. [Persona](/docs/6-persona.md)
-1. [Extensions](/docs/8-extensions.md)
-1. [Environment variables](/docs/9-environment-variables.md)
-1. [Migration considerations](/docs/migration.md)
+2. [Solution Overview](./docs/1-introduction.md)
+3. [Run from your local machine](./docs/2-run-locally.md)
+4. [Add identity provider](./docs/3-add-identity.md)
+5. [Deploy to Azure](#deploy-to-azure)
+6. [Deploy to Azure with GitHub Actions](./docs/4-deploy-to-azure.md)
+7. [Chatting with your file](./docs/5-chat-over-file.md)
+8. [Persona](./docs/6-persona.md)
+9. [Extensions](./docs/7-extensions.md)
+10. [Environment variables](./docs/8-environment-variables.md)
+11. [Managed Identity-based deployment](./docs/9-managed-identities.md)
+12. [Migration considerations](./docs/migration.md)
 
 # Introduction
 
 _Azure Chat Solution Accelerator powered by Azure OpenAI Service_
 
-![](/docs/images/intro.png)
+![Intro Image](/docs/images/intro.png)
 
 _Azure Chat Solution Accelerator powered by Azure OpenAI Service_ is a solution accelerator that allows organisations to deploy a private chat tenant in their Azure Subscription, with a familiar user experience and the added capabilities of chatting over your data and files.
 
 Benefits are:
 
-1. Private: Deployed in your Azure tenancy, allowing you to isolate it to your Azure tenant.
+1. **Private:** Deployed in your Azure tenancy, allowing you to isolate it to your Azure tenant.
 
-2. Controlled: Network traffic can be fully isolated to your network and other enterprise grade authentication security features are built in.
+2. **Controlled:** Network traffic can be fully isolated to your network and other enterprise grade authentication security features are built in.
 
-3. Value: Deliver added business value with your own internal data sources (plug and play) or integrate with your internal services (e.g., ServiceNow, etc).
+3. **Value:** Deliver added business value with your own internal data sources (plug and play) or integrate with your internal services (e.g., ServiceNow, etc).
 
 # Deploy to Azure
 
-You can provision Azure resources for the solution accelerator using either the Azure Developer CLI or the Deploy to Azure button below. Regardless of the method you chose you will still need set up an [identity provider and specify an admin user](/docs/5-add-identity.md)
+You can provision Azure resources for the solution accelerator using either the Azure Developer CLI or the Deploy to Azure button below. Regardless of the method you chose you will still need set up an [identity provider and specify an admin user](/docs/3-add-identity.md).
+
+We recommend you also read the dedicated [Deploy to Azure](./docs/4-deploy-to-azure.md) documentation to understand how to deploy the application using GitHub Actions.
 
 ## Deployment Options
 
@@ -66,9 +76,9 @@ Click on the Deploy to Azure button to deploy the Azure resources for the applic
 [![Deploy to Azure](https://aka.ms/deploytoazurebutton)](https://aka.ms/anzappazurechatgpt)
 
 > [!IMPORTANT]
-> The application is protected by an identity provider and follow the steps in [Add an identity provider](/docs/5-add-identity.md) section for adding authentication to your app.
+> The application is protected by an identity provider, follow the steps in [Add an identity provider](/docs/3-add-identity.md) section for adding authentication to your app.
 
-[Next](./docs/1-introduction.md)
+[Next: Introduction](./docs/1-introduction.md)
 
 # Contributing
 

azure.yaml

@@ -12,9 +12,9 @@ hooks:
   postdeploy:
     posix:
       shell: sh
-      run: echo -e "\n\033[0;36mTo complete the application setup you will need to configure an identity provider\033[0m\n(see the "Production App Setup" documentation at https://github.com/microsoft/azurechat/blob/main/docs/5-add-identity.md)\n"
+      run: echo -e "\n\033[0;36mTo complete the application setup you will need to configure an identity provider\033[0m\n(see the "Production App Setup" documentation at https://github.com/microsoft/azurechat/blob/main/docs/3-add-identity.md)\n"
       interactive: true
       continueOnError: false
     windows:
       shell: pwsh
-      run: Write-Host "`nTo complete the application setup you will need to configure an identity provider`n(see the 'Production App Setup' documentation at https://github.com/microsoft/azurechat/blob/main/docs/5-add-identity.md)`n" -ForegroundColor Cyan
+      run: Write-Host "`nTo complete the application setup you will need to configure an identity provider`n(see the 'Production App Setup' documentation at https://github.com/microsoft/azurechat/blob/main/docs/3-add-identity.md)`n" -ForegroundColor Cyan

docs/1-introduction.md

@@ -2,31 +2,29 @@
 
 Please make sure the following prerequisites are in place prior to deploying this accelerator:
 
-1. [Azure OpenAI](https://azure.microsoft.com/en-us/products/cognitive-services/openai-service/): To deploy and run the solution accelerator, you'll need an Azure subscription with access to the Azure OpenAI service. Request access [here](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xUOFA5Qk1UWDRBMjg0WFhPMkIzTzhKQ1dWNyQlQCN0PWcu). Once you have access, follow the instructions in this [link](https://learn.microsoft.com/en-us/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal) to deploy the gpt-35-turbo or gpt-4 models.
-
-2. Setup GitHub or Azure AD for Authentication:
-   The [add an identity provider](./5-add-identity.md) section below shows how to configure authentication providers.
+1. Setup GitHub or Entra ID for authentication:
+   The [add an identity provider](./3-add-identity.md) section below shows how to configure authentication providers.
 
 > [!NOTE]
 > You can configure the authentication provider to your identity solution using [NextAuth providers](https://next-auth.js.org/providers/)
 
 ## 👋🏻 Introduction
 
-_Azure Chat Solution Accelerator powered by Azure Open AI Service_ solution accelerator is built using the following technologies:
+_Azure Chat Solution Accelerator powered by Azure OpenAI Service_ is built using the following technologies:
 
-- [Node.js 18](https://nodejs.org/en): an open-source, cross-platform JavaScript runtime environment.
+- [Node.js 22](https://nodejs.org/en): an open-source, cross-platform JavaScript runtime environment.
 
-- [Next.js 13](https://nextjs.org/docs): enables you to create full-stack web applications by extending the latest React features
+- [Next.js 14](https://nextjs.org/docs): enables you to create full-stack web applications by extending the latest React features.
 
-- [NextAuth.js](https://next-auth.js.org/): configurable authentication framework for Next.js 13
+- [NextAuth.js](https://next-auth.js.org/): configurable authentication framework for Next.js.
 
-- [OpenAI sdk](https://github.com/openai/openai-node) NodeJS library that simplifies building conversational UI
+- [OpenAI SDK](https://github.com/openai/openai-node) NodeJS library that simplifies building conversational UI.
 
-- [Tailwind CSS](https://tailwindcss.com/): is a utility-first CSS framework that provides a series of predefined classes that can be used to style each element by mixing and matching
+- [Tailwind CSS](https://tailwindcss.com/): is a utility-first CSS framework that provides a series of predefined classes that can be used to style each element by mixing and matching.
 
 - [shadcn/ui](https://ui.shadcn.com/): re-usable components built using Radix UI and Tailwind CSS.
 
-- [Azure Cosmos DB](https://learn.microsoft.com/en-GB/azure/cosmos-db/nosql/): fully managed platform-as-a-service (PaaS) NoSQL database to store chat history
+- [Azure Cosmos DB](https://learn.microsoft.com/en-GB/azure/cosmos-db/nosql/): fully managed platform-as-a-service (PaaS) NoSQL database to store chat history.
 
 - [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview): Azure OpenAI Service provides REST API access to OpenAI's powerful language models including the GPT-4, GPT-35-Turbo, and Embeddings model series.
 
@@ -36,35 +34,37 @@ _Azure Chat Solution Accelerator powered by Azure Open AI Service_ solution acce
 
 The following Azure services can be deployed to expand the feature set of your solution:
 
-- [Azure Document Intelligence](https://learn.microsoft.com/en-GB/azure/ai-services/document-intelligence/) Microsoft Azure Form Recognizer is an automated data processing system that uses AI and OCR to quickly extract text and structure from documents. We use this service for extracting information from documents.
+- [Azure AI Document Intelligence](https://learn.microsoft.com/en-GB/azure/ai-services/document-intelligence/): an automated data processing system that uses AI and OCR to quickly extract text and structure from documents. We use this service for extracting information from documents.
 
-- [Azure AI Search ](https://learn.microsoft.com/en-GB/azure/search/) Azure AI Search is an AI-powered platform as a service (PaaS) that helps developers build rich search experiences for applications. We use this service for indexing and retrieving information.
+- [Azure AI Search](https://learn.microsoft.com/en-GB/azure/search/): an AI-powered Platform-as-a-Service (PaaS) that helps developers build rich search experiences for applications. We use this service for indexing and retrieving information.
 
-- [Azure OpenAI Embeddings](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/embeddings?tabs=console) for embed content extracted from files.
+- [Azure OpenAI Embeddings](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/embeddings?tabs=console): to embed content extracted from files prior to indexing and during retrieval (vector search).
 
-- [Azure Speech Service](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/): Speech recognition and generation with multi-lingual support and the ability to select and create custom voices.
+- [Azure AI Speech](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/): speech recognition and generation with multi-lingual support and the ability to select and create custom voices.
 
 # Solution Architecture
 
 The following high-level diagram depicts the architecture of the solution accelerator:
 
-![Architecture diagram](/docs/images/architecture.png)
+![Architecture diagram](./images/architecture.png)
 
 # Azure Deployment Costs
 
 Pricing varies per region and usage, so it isn't possible to predict exact costs for your usage.
 However, you can try the [Azure pricing calculator - Sample Estimate](https://azure.com/e/1f08b35661df4b5ea3663df112250b09) for the resources below.
 
 - Azure App Service: Premium V3 Tier 1 CPU core, 4 GB RAM, 250 GB Storage. Pricing per hour. [Pricing](https://azure.microsoft.com/pricing/details/app-service/linux/)
-- Azure Open AI: Standard tier, ChatGPT and Embedding models. Pricing per 1K tokens used, and at least 1K tokens are used per question. [Pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/openai-service/)
-- Form Recognizer: SO (Standard) tier using pre-built layout. Pricing per document page, sample documents have 261 pages total. [Pricing](https://azure.microsoft.com/pricing/details/form-recognizer/)
-- Azure AI Search : Standard tier, 1 replica, free level of semantic search. Pricing per hour.[Pricing](https://azure.microsoft.com/pricing/details/search/)
+- Azure OpenAI: Standard tier, ChatGPT and Embedding models. Pricing per 1K tokens used, and at least 1K tokens are used per question. [Pricing](https://azure.microsoft.com/en-us/pricing/details/cognitive-services/openai-service/)
+- Azure AI Document Intelligence: SO (Standard) tier using pre-built layout. Pricing per document page, sample documents have 261 pages total. [Pricing](https://azure.microsoft.com/en-us/pricing/details/ai-document-intelligence/)
+- Azure AI Search: Standard tier, 1 replica, free level of semantic search. Pricing per hour.[Pricing](https://azure.microsoft.com/pricing/details/search/)
 - Azure Cosmos DB: Standard provisioned throughput with ZRS (Zone-redundant storage). Pricing per storage and read operations. [Pricing](https://azure.microsoft.com/en-us/pricing/details/cosmos-db/autoscale-provisioned/)
 - Azure Monitor: Pay-as-you-go tier. Costs based on data ingested. [Pricing](https://azure.microsoft.com/pricing/details/monitor/)
 
-To reduce costs, you can switch to free SKUs for Azure App Service, Azure AI Search , and Form Recognizer by changing the parameters file under the `./infra` folder. There are some limits to consider; for example, you can have up to 1 free Cognitive Search resource per subscription, and the free Form Recognizer resource only analyzes the first 2 pages of each document. You can also reduce costs associated with the Form Recognizer by reducing the number of documents you upload.
+To reduce costs, you can switch to free SKUs for Azure App Service, Azure AI Search, and Azure AI Document Intelligence by changing the parameters file under the `./infra` folder. There are some limitations to consider; for example, you can have up to 1 free Azure AI Search resource per subscription, and the free Azure AI Document Intelligence resource which only analyzes 500 pages for free each month. You can also reduce costs associated with the Azure AI Document Intelligence service by reducing the number of documents you upload.
 
 > [!WARNING]
 > To avoid unnecessary costs, remember to destroy your provisioned resources by deleting the resource group.
 
-[Next](/docs/2-provision-azure-resources.md)
+## Continue to the next step...
+
+👉 [Next: Run Azure Chat Locally (development)](./2-run-locally.md)

docs/2-run-locally.md

@@ -0,0 +1,26 @@
+# 👨🏻‍💻 Run Locally
+
+Clone this repository locally or fork to your GitHub account. Run all of the the steps below from the `src` directory.
+
+## Prerequisites
+
+- **History Database**: If you don't want to [provision the Azure resources](./4-deploy-to-azure.md), you **must** at least deploy an instance of Azure Cosmos DB in your Azure Subscription to store chat history.
+
+- **Identity Provider**: For local development, you have the option of using a username / password to sign in. If you prefer to use an Identity Provider, follow the [instructions](./3-add-identity.md) in the next chapter to add one.
+
+## Steps to Run Locally
+
+1. Change directory to the `src` folder
+2. Rename/copy the file `.env.example` to `.env.local` and populate the environment variables based on the deployed resources in Azure.
+3. Install npm packages by running `npm install`
+4. Start the app by running `npm run dev`
+5. Access the app on [http://localhost:3000](http://localhost:3000)
+
+You should now be prompted to log in with your chosen authentication method (per the pre-requisite configuration).
+
+> **NOTE**
+> If using Basic Auth (DEV ONLY), any username you enter will create a new user id (hash of username@localhost). You can use this to simulate multiple users. Once successfully logged in, you can start creating new conversations.
+
+## Continue to the next step...
+
+👉 [Next: Add an Identity Provider](./3-add-identity.md)