# IF-APIM-to-Copilot-Studio

**Repository Path**: mirrors_microsoft/IF-APIM-to-Copilot-Studio

## Basic Information

- **Project Name**: IF-APIM-to-Copilot-Studio
- **Description**: A collection of sample applications that demonstrate connecting to Copilot Studio through Azure API Management (APIM).
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-23
- **Last Updated**: 2025-11-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Copilot Studio Integration Demos with Azure API Management

A comprehensive collection of demo applications showcasing how to integrate **Microsoft Copilot Studio** with various application platforms and frameworks using **Azure API Management (APIM)** as a secure gateway. Each demo implements Azure Entra ID (formerly Azure AD) authentication and establishes a connection to Copilot Studio through APIM.

## Overview

This repository contains **five complete demo applications**, each built with a different technology stack, demonstrating best practices for integrating conversational AI into your applications with enterprise-grade security:

- **Angular** - Modern web application using Angular framework
- **React** - Single-page application built with React and Vite
- **ASP.NET Core MVC** - Server-side web application with MVC pattern
- **WPF** - Windows desktop application with integrated authentication
- **dotnetcore** - Console application for terminal-based chatbot interaction

All applications share common functionality:
- User authentication via Azure Entra ID
- **Secure access through Azure API Management (APIM)**
- Copilot Studio chatbot integration via Direct Line
- JWT token validation and user-based rate limiting
- Single Sign-On (SSO) with token passthrough
- Secure credential handling and token management

## Architecture

### Architecture (with APIM)

```
┌─────────────┐        ┌──────────┐        ┌─────────────┐        ┌────────────────┐
│  Application│        │  Entra   │        │    APIM     │        │ Copilot Studio │
│             │───────▶│   ID     │───────▶│   Gateway   │───────▶│ (Direct Line)  │
│             │  Auth  │          │  JWT   │             │ Secret │                │
└─────────────┘        └──────────┘        └─────────────┘        └────────────────┘
```

**Flow**: `App → Entra ID (get JWT) → APIM (validate JWT) → Direct Line → Copilot Studio`

### Benefits of APIM Integration

1. **Enhanced Security**
   - Direct Line secret never exposed to client applications
   - Centralized JWT token validation
   - User-based rate limiting and throttling
   - IP filtering and access control

2. **Enterprise Features**
   - Comprehensive monitoring and analytics
   - Centralized policy management
   - Request/response transformation
   - API versioning and management

3. **SSO & Token Management**
   - Seamless Single Sign-On experience
   - Automatic token passthrough to Copilot Studio
   - Token validation and refresh handling

**📘 For detailed APIM setup instructions, see [APIM-SETUP.md](./APIM-SETUP.md)**

## Demo Applications

### 1. Angular Application (`/angular`)

**Single-page web application built with Angular**

- **Framework**: Angular 19
- **Authentication**: MSAL Angular (@azure/msal-angular)
- **UI**: Modern, responsive design
- **Port**: http://localhost:4200

A clean, modern web application demonstrating how to integrate Copilot Studio into Angular applications. Features Azure Entra ID authentication with MSAL and seamless webchat integration.

[View Angular README →](./angular/README.md)

### 2. React Application (`/react`)

**Single-page web application built with React**

- **Framework**: React 18 + Vite
- **Authentication**: MSAL React (@azure/msal-react)
- **UI**: Clean, component-based architecture
- **Port**: http://localhost:5173

A React-based implementation showcasing Copilot Studio integration with modern React patterns, hooks, and TypeScript. Built with Vite for fast development experience.

[View React README →](./react/README.md)

### 3. ASP.NET Core MVC Application (`/mvc`)

**Server-side web application with MVC pattern**

- **Framework**: ASP.NET Core 8.0 MVC
- **Authentication**: Microsoft.Identity.Web (OpenID Connect)
- **UI**: Bootstrap-based responsive design
- **Port**: https://localhost:7xxx (HTTPS)

A traditional server-side MVC application demonstrating enterprise-grade authentication and Copilot Studio integration. Features session management and server-side configuration handling.

[View MVC README →](./mvc/README.md)

### 4. WPF Desktop Application (`/wpf`)

**Windows desktop application with integrated authentication**

- **Framework**: WPF (.NET 8.0)
- **Authentication**: MSAL.NET with Windows Integrated Auth
- **UI**: WebView2-embedded chat interface
- **Platform**: Windows 10+ (version 1803 or later)

A Windows desktop application featuring **automatic Single Sign-On** using Windows Integrated Authentication. The app automatically authenticates the current Windows user and passes their credentials to Copilot Studio.

**Special Features**:
- Windows Integrated Authentication (automatic SSO)
- Token-based authentication passed to bot
- WebView2 for seamless browser-based chat experience
- Native Windows application experience

[View WPF README →](./wpf/README.md)

### 5. .NET Core Console Application (`/dotnetcore`)

**Command-line chatbot interface**

- **Framework**: .NET Core 8.0 Console
- **Authentication**: MSAL.NET with device code flow
- **Interface**: Terminal/console-based chat
- **Platform**: Cross-platform (Windows, macOS, Linux)

A console application that brings Copilot Studio to the terminal. Features interactive authentication, continuous chat loop, and SSO token passing. Type messages and receive responses directly in your terminal. Type `exit` to quit.

**Special Features**:
- Interactive command-line chat experience
- Automatic token refresh
- Context preservation across conversation
- Cross-platform compatibility

[View .NET Core Console README →](./dotnetcore/README.md)

## Architecture & Common Patterns

All demo applications follow these architectural patterns:

### Authentication Flow

1. **User Authentication**: User authenticates with Azure Entra ID
2. **Token Acquisition**: Application obtains access token via MSAL
3. **APIM Validation**: APIM validates JWT token and user claims
4. **Copilot Connection**: APIM forwards request to Copilot Studio via Direct Line
5. **SSO**: Access token passed through APIM to Copilot Studio for seamless authentication

### Technology Stack

| Component | Technology |
|-----------|------------|
| **Authentication** | Azure Entra ID (formerly Azure AD) |
| **Auth Library** | MSAL (Microsoft Authentication Library) |
| **API Gateway** | Azure API Management (APIM) |
| **Bot Integration** | Bot Framework Direct Line API |
| **Chatbot Platform** | Microsoft Copilot Studio |
| **Token Management** | Silent token refresh with fallback |
| **Security** | JWT validation, rate limiting, throttling |

### APIM Integration

All applications connect through **Azure API Management** which provides:

- **Security**: JWT token validation, Direct Line secret protection
- **Rate Limiting**: Per-user throttling and quotas
- **Monitoring**: Request/response tracking and analytics
- **Message Format**: Bot Framework Activity protocol
- **User Context**: Extracted from JWT claims and passed to Copilot Studio
- **SSO Token**: Access token passed via `channelData` for Single Sign-On

## Prerequisites

Before running any of these applications, you'll need:

### 1. Azure Entra ID App Registration

- An **Azure subscription**
- A **registered application** in Azure Entra ID
- **Client ID** and **Tenant ID** from your app registration
- **API scope** exposed: `api://YOUR_CLIENT_ID/access_as_user`
- Appropriate **redirect URIs** configured for your chosen platform:
  - Angular SPA: `http://localhost:4200`
  - React SPA: `http://localhost:5173`
  - MVC Web: `https://localhost:7xxx/signin-oidc`
  - WPF Desktop: Public client/native
  - Console: Public client/native

### 2. Azure API Management (APIM)

- An **APIM instance** (Developer tier minimum)
- **APIM endpoint** configured with Copilot Studio API
- **Direct Line secret** stored as Named Value in APIM
- **APIM policies** configured for JWT validation and rate limiting
- **📘 See [APIM-SETUP.md](./APIM-SETUP.md) for detailed setup instructions**

### 3. Microsoft Copilot Studio Bot

- A **Copilot Studio** bot (create at [copilotstudio.microsoft.com](https://copilotstudio.microsoft.com))
- **Direct Line channel** enabled
- **Direct Line secret key** (stored in APIM, not in apps)

### 4. Development Tools

Depending on which demo you want to run:

- **Node.js** (v18+) - for Angular and React apps
- **.NET 8.0 SDK** - for MVC, WPF, and Console apps
- **Visual Studio** or **VS Code** - recommended IDEs
- **Windows 10+** - required for WPF app only

## Quick Start

### Common Setup Steps

1. **Clone this repository**
   ```bash
   git clone <repository-url>
   cd apim-copilot-studio
   ```

2. **Register an Azure Entra ID application**
   - Go to [Azure Portal](https://portal.azure.com)
   - Navigate to **Azure Active Directory** > **App registrations** > **New registration**
   - Configure redirect URIs based on which demo you're running
   - **Expose an API** with scope `api://YOUR_CLIENT_ID/access_as_user`
   - Note your **Client ID** and **Tenant ID**

3. **Set up Azure API Management**
   - Create an APIM instance (Developer tier or higher)
   - Configure Copilot Studio API in APIM
   - Add Direct Line operations (start conversation, send/get activities)
   - Configure APIM policies for JWT validation and rate limiting
   - **📘 Follow the complete guide in [APIM-SETUP.md](./APIM-SETUP.md)**

4. **Configure Copilot Studio**
   - Go to [Copilot Studio](https://copilotstudio.microsoft.com)
   - Create or open your bot
   - Enable **Direct Line** channel and copy the **Secret key**
   - Configure **Authentication** with Azure AD for SSO
   - **Store Direct Line secret in APIM Named Values (not in your app)**
   - **📘 See [COPILOT-SETUP.md](./COPILOT-SETUP.md) for complete Copilot Studio configuration**

5. **Choose a demo and configure it**
   - Navigate to the desired demo folder
   - Update configuration files with your:
     - Azure AD Client ID and Tenant ID
     - **APIM endpoint** (e.g., `https://your-apim.azure-api.net/bot`)
   - Follow the specific README for that demo

**⚠️ Important**: Applications do not use Direct Line secret directly. The secret is stored securely in APIM, and apps authenticate using Azure AD tokens.

### Running Individual Demos

#### Angular
```bash
cd angular
npm install
# Update src/environments/environment.ts with your credentials
npm start
```

#### React
```bash
cd react
npm install
# Update src/config.ts with your credentials
npm run dev
```

#### ASP.NET Core MVC
```bash
cd mvc
# Update appsettings.json with your credentials
dotnet run
```

#### WPF Desktop
```bash
cd wpf
# Update appsettings.json with your credentials
dotnet run
```

#### .NET Core Console
```bash
cd dotnetcore
# Update appsettings.json with your credentials
dotnet run
```

## Configuration

Each application requires similar configuration values. Here's what you'll need to provide:

### Azure Entra ID Configuration

```json
{
  "ClientId": "YOUR_APPLICATION_CLIENT_ID",
  "ClientSecret": "YOUR_CLIENT_SECRET",
  "TenantId": "YOUR_TENANT_ID",
  "Authority": "https://login.microsoftonline.com/YOUR_TENANT_ID",
  "Scopes": ["api://YOUR_CLIENT_ID/access_as_user"]
}
```

### APIM Configuration

```json
{
  "Endpoint": "https://YOUR_APIM_NAME.azure-api.net/bot"
}
```

**Important Notes**:
- **Never commit credentials to source control**. Use environment variables or Azure Key Vault for production deployments
- **Direct Line secret** is now stored in APIM Named Values, not in application configuration
- **APIM endpoint** replaces direct Direct Line connections in all apps
- Applications use **Azure AD tokens** to authenticate with APIM, which then uses the Direct Line secret to connect to Copilot Studio

## Project Structure

```
apim-copilot-studio/
├── README.md                    # This file
├── LICENSE.md                   # MIT License
├── APIM-SETUP.md                # Complete APIM setup guide
├── COPILOT-SETUP.md             # Copilot Studio configuration guide
├── .gitignore                   # Git ignore rules
├── angular/                     # Angular demo application
│   ├── src/
│   ├── package.json
│   └── README.md
├── react/                       # React demo application
│   ├── src/
│   ├── package.json
│   └── README.md
├── mvc/                         # ASP.NET Core MVC demo
│   ├── Controllers/
│   ├── Views/
│   ├── appsettings.json
│   └── README.md
├── wpf/                         # WPF desktop demo
│   ├── Services/
│   ├── Assets/
│   ├── appsettings.json
│   └── README.md
└── dotnetcore/                  # Console application demo
    ├── Services/
    ├── Program.cs
    ├── appsettings.json
    └── README.md
```

## Features Comparison

| Feature | Angular | React | MVC | WPF | Console |
|---------|---------|-------|-----|-----|---------|
| **Platform** | Web | Web | Web | Desktop | Terminal |
| **Authentication** | MSAL Browser | MSAL Browser | MSAL Web | MSAL Desktop | MSAL Desktop |
| **UI Type** | SPA | SPA | Server-rendered | Native Windows | CLI |
| **SSO Token Passing** | ✓ | ✓ | ✓ | ✓ | ✓ |
| **Windows Integrated Auth** | ✗ | ✗ | ✗ | ✓ | ✗ |
| **Cross-Platform** | ✓ | ✓ | ✓ | ✗ (Windows only) | ✓ |
| **Offline Capable** | Limited | Limited | ✗ | ✓ | ✓ |
| **Development Server** | ✓ | ✓ | ✓ | ✗ | ✗ |

## Security Considerations

- **Never commit credentials**: Use `.gitignore` to exclude configuration files with secrets
- **Use HTTPS in production**: All web apps should use HTTPS in production
- **Token storage**: MSAL handles secure token caching automatically
- **Secret management**: Use Azure Key Vault for production deployments
- **CORS configuration**: Configure Copilot Studio's allowed origins properly
- **Token refresh**: All apps implement automatic token refresh

## Troubleshooting

### Common Issues

**Authentication fails**
- Verify your Client ID and Tenant ID are correct
- Check that redirect URIs match exactly in Azure portal
- Ensure the app registration has required API permissions

**Copilot Studio doesn't respond**
- Verify the Direct Line secret is correct and not expired
- Check that the Direct Line channel is enabled in Copilot Studio
- Ensure your bot is published in Copilot Studio

**CORS errors (web apps)**
- Direct Line handles CORS automatically
- Ensure you're not mixing HTTP/HTTPS incorrectly

**Build errors**
- Make sure you have the correct SDK/Node.js version installed
- Run `npm install` or `dotnet restore` to install dependencies
- Check individual project READMEs for specific requirements

## Additional Resources

### Microsoft Documentation

- [Microsoft Copilot Studio](https://docs.microsoft.com/power-virtual-agents/)
- [Azure Entra ID](https://docs.microsoft.com/azure/active-directory/)
- [MSAL Overview](https://docs.microsoft.com/azure/active-directory/develop/msal-overview)
- [Bot Framework Direct Line API](https://docs.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-concepts)

### Related Technologies

- [Angular](https://angular.io/)
- [React](https://react.dev/)
- [ASP.NET Core](https://docs.microsoft.com/aspnet/core/)
- [WPF](https://docs.microsoft.com/dotnet/desktop/wpf/)
- [.NET](https://dotnet.microsoft.com/)

## Contributing

This repository contains demonstration applications for educational purposes. Each application is self-contained and can be used as a starting point for your own Copilot Studio integration.

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

This sample code is provided as-is for demonstration and educational purposes.

## Support

For issues specific to:
- **Azure Entra ID**: Check [Azure AD documentation](https://docs.microsoft.com/azure/active-directory/)
- **Copilot Studio**: Visit [Copilot Studio community](https://powerusers.microsoft.com/t5/Microsoft-Copilot-Studio/ct-p/PVACommunity)
- **MSAL**: See [MSAL documentation](https://docs.microsoft.com/azure/active-directory/develop/msal-overview)

## Getting Help

Each demo application has its own detailed README with specific setup instructions, troubleshooting tips, and example usage. Please refer to the individual README files for detailed information:

- [Angular README](./angular/README.md)
- [React README](./react/README.md)
- [MVC README](./mvc/README.md)
- [WPF README](./wpf/README.md)
- [.NET Core Console README](./dotnetcore/README.md)

---

**Happy coding!** Choose the demo that best fits your technology stack and start building intelligent conversational experiences with Microsoft Copilot Studio.