microsoft/teams.net
Publicmirrored fromhttps://github.com/microsoft/teams.netAvailable
Samples/Samples.Graph/README.md
120lines · modecode
| 1 | # Graph Sample |
| 2 | |
| 3 | This sample demonstrates how to implement OAuth authentication and Microsoft Graph integration in a Teams bot using the Teams AI SDK for .NET. |
| 4 | |
| 5 | ## Features |
| 6 | |
| 7 | - OAuth authentication with Microsoft Graph |
| 8 | - User sign-in/sign-out functionality |
| 9 | - Access to Microsoft Graph API (user profile information) |
| 10 | - Custom sign-in UI with configurable text |
| 11 | - Token display after successful authentication |
| 12 | |
| 13 | ## Prerequisites |
| 14 | |
| 15 | - .NET 9.0 |
| 16 | - Azure Bot Service registration |
| 17 | - Microsoft Graph OAuth connection configured in Azure Bot Service |
| 18 | - Dev tunnels or ngrok for local development |
| 19 | |
| 20 | ## Project Structure |
| 21 | |
| 22 | ``` |
| 23 | Samples.Graph/ |
| 24 | ├── Program.cs # Main bot logic and OAuth handlers |
| 25 | ├── Samples.Graph.csproj # Project file with SDK dependencies |
| 26 | ├── appsettings.json # Bot credentials configuration |
| 27 | ├── Properties/launchSettings.json # Launch configuration (port 3978) |
| 28 | └── README.md # This file |
| 29 | ``` |
| 30 | |
| 31 | ## Setup |
| 32 | |
| 33 | ### 1. Azure Bot Registration |
| 34 | 1. Create an Azure Bot resource in the Azure Portal |
| 35 | 2. Configure the messaging endpoint: `https://your-tunnel-url/api/messages` |
| 36 | 3. Note the Application (Client) ID and create a Client Secret |
| 37 | |
| 38 | ### 2. OAuth Connection Setup |
| 39 | 1. In your Azure Bot resource, go to **Configuration** → **OAuth Connection Settings** |
| 40 | 2. Add new OAuth connection: |
| 41 | - **Name**: `graph` (must match the code) |
| 42 | - **Service Provider**: `Generic Oauth 2` or `Azure Active Directory v2` |
| 43 | - **Client ID**: Your bot's Application (Client) ID |
| 44 | - **Client Secret**: Your bot's client secret |
| 45 | - **Authorization URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/authorize` |
| 46 | - **Token URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/token` |
| 47 | - **Refresh URL**: `https://login.microsoftonline.com/common/oauth2/v2.0/token` |
| 48 | - **Scopes**: `User.Read` |
| 49 | |
| 50 | ### 3. Update Configuration |
| 51 | Update `appsettings.json` with your bot credentials: |
| 52 | ```json |
| 53 | { |
| 54 | "Teams": { |
| 55 | "ClientId": "your-bot-application-id", |
| 56 | "ClientSecret": "your-bot-client-secret" |
| 57 | } |
| 58 | } |
| 59 | ``` |
| 60 | |
| 61 | ### 4. Local Development Setup |
| 62 | 1. Install dev tunnels: `winget install Microsoft.DevTunnels` |
| 63 | 2. Create tunnel: `devtunnel create -a` |
| 64 | 3. Host tunnel: `devtunnel host <tunnel-id> -p 3978` |
| 65 | 4. Update Azure Bot messaging endpoint with the tunnel URL |
| 66 | |
| 67 | ## Running the Sample |
| 68 | |
| 69 | ```bash |
| 70 | # Navigate to the project directory |
| 71 | cd Samples/Samples.Graph |
| 72 | |
| 73 | # Run the bot |
| 74 | dotnet run |
| 75 | ``` |
| 76 | |
| 77 | The bot will start on `http://localhost:3978` by default. |
| 78 | |
| 79 | ## Usage |
| 80 | |
| 81 | ### Authentication Flow |
| 82 | 1. **Initial Message**: Send any message to the bot to trigger sign-in |
| 83 | 2. **Sign-in Card**: Bot presents OAuth sign-in card with custom text |
| 84 | 3. **Authentication**: Complete OAuth flow with Microsoft Graph |
| 85 | 4. **Success Response**: Bot displays user's display name and access token |
| 86 | |
| 87 | ### Commands |
| 88 | - **Any message**: Triggers sign-in flow if not authenticated, shows user info if authenticated |
| 89 | - **`/signout`**: Signs out the current user and clears authentication |
| 90 | |
| 91 | ### Expected Responses |
| 92 | - **Not signed in**: "Sign in to your account" OAuth card |
| 93 | - **Already signed in**: "user 'DisplayName' is already signed in!" |
| 94 | - **After sign-in**: "user \"DisplayName\" signed in. Here's the token: [token]" |
| 95 | - **Sign-out**: "you have been signed out!" |
| 96 | |
| 97 | ## Key Components |
| 98 | |
| 99 | - **OAuth Integration**: Configured with `.AddOAuth("graph")` (Program.cs:13) |
| 100 | - **Sign-in Handler**: Main message handler with `SignInOptions` (Program.cs:32-48) |
| 101 | - **Sign-out Handler**: Dedicated `/signout` command handler (Program.cs:20-30) |
| 102 | - **Sign-in Event**: Handles successful authentication and token display (Program.cs:50-57) |
| 103 | - **Graph API Access**: Uses `context.UserGraph.Me.GetAsync()` for user profile (Program.cs:46, 55) |
| 104 | |
| 105 | ## Dependencies |
| 106 | |
| 107 | The project references the following Teams AI SDK libraries: |
| 108 | - `Microsoft.Teams.Apps` - Core Teams bot functionality |
| 109 | - `Microsoft.Teams.Api` - Teams API models and clients |
| 110 | - `Microsoft.Teams.Common` - Common utilities and logging |
| 111 | - `Microsoft.Teams.Cards` - Adaptive Cards support |
| 112 | - `Microsoft.Teams.Extensions.Hosting` - ASP.NET Core integration |
| 113 | - `Microsoft.Teams.Plugins.AspNetCore` - ASP.NET Core plugin support |
| 114 | |
| 115 | ## Troubleshooting |
| 116 | |
| 117 | - **Authentication fails**: Verify OAuth connection name matches "graph" in code |
| 118 | - **Bot not reachable**: Ensure dev tunnel is running and messaging endpoint is correct |
| 119 | - **Permission errors**: Check Azure Bot and App Registration have correct permissions |
| 120 | - **Token issues**: Verify OAuth scopes include `User.Read` for Microsoft Graph access |