Fix Issue #2880: Document the usage of the AAD auth (#2941)

* Document the usage of the AAD auth. #2880 Added the document for the usage of AAD ! * Update website/docs/topics/llm_configuration.ipynb Co-authored-by: Qingyun Wu <[email protected]> * Updated Location and Link to Azure OpenAI documentation * Update AutoTX Link on Gallery.json (#3082) Co-Authored-By: Qingyun Wu <[email protected]> Co-Authored-By: Yiran Wu <[email protected]> Co-Authored-By: Chi Wang <[email protected]> * Making the required changes Updated function description and parameter description as well. Also, created the corresponding cs file for the t4 file. And created the new test case and updated the checks as well. * Revert "Making the required changes" By mistake * Update llm_configuration.ipynb --------- Co-authored-by: Li Jiang <[email protected]> Co-authored-by: Chi Wang <[email protected]> Co-authored-by: Qingyun Wu <[email protected]> Co-authored-by: Yiran Wu <[email protected]>
microsoft · Aug 2, 2024 · 56007d1 · 56007d1
1 parent 354dca8
commit 56007d1
Showing 1 changed file with 120 additions and 0 deletions.
diff --git a/website/docs/topics/llm_configuration.ipynb b/website/docs/topics/llm_configuration.ipynb
@@ -293,6 +293,126 @@
     "}"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using Azure Active Directory (AAD) Authentication\n",
+    "\n",
+    "Azure Active Directory (AAD) provides secure access to resources and applications. Follow the steps below to configure AAD authentication for Autogen.\n",
+    "\n",
+    "#### Prerequisites\n",
+    "- An Azure subscription - [Create one for free](https://azure.microsoft.com/en-us/free/).\n",
+    "- Access granted to the Azure OpenAI Service in the desired Azure subscription.\n",
+    "- Appropriate permissions to register an application in AAD.\n",
+    "- Custom subdomain names are required to enable features like Microsoft Entra ID for authentication.\n",
+    "- Azure CLI - [Installation Guide](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli).\n",
+    "\n",
+    "For more detailed and up-to-date instructions, please refer to the official [Azure OpenAI documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/).\n",
+    "\n",
+    "#### Step 1: Register an Application in AAD\n",
+    "1. Navigate to the [Azure portal](https://azure.microsoft.com/en-us/get-started/azure-portal).\n",
+    "2. Go to `Azure Active Directory` > `App registrations`.\n",
+    "3. Click on `New registration`.\n",
+    "4. Enter a name for your application.\n",
+    "5. Set the `Redirect URI` (optional).\n",
+    "6. Click `Register`.\n",
+    "\n",
+    "For detailed instructions, refer to the official [Azure AD Quickstart documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate).\n",
+    "\n",
+    "#### Step 2: Configure API Permissions\n",
+    "1. After registration, go to `API permissions`.\n",
+    "2. Click `Add a permission`.\n",
+    "3. Select `Microsoft Graph` and then `Delegated permissions`.\n",
+    "4. Add the necessary permissions (e.g., `User.Read`).\n",
+    "\n",
+    "For more details, see [API permissions in Microsoft Graph](https://learn.microsoft.com/en-us/entra/identity-platform/permissions-consent-overview)\n",
+    "\n",
+    "#### Step 3: Obtain Client ID and Tenant ID\n",
+    "1. Go to `Overview` of your registered application.\n",
+    "2. Note down the `Application (client) ID` and `Directory (tenant) ID`.\n",
+    "\n",
+    "For more details, visit [Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate)\n",
+    "\n",
+    "#### Step 4: Configure Your Application\n",
+    "Use the obtained `Client ID` and `Tenant ID` in your application configuration. Here’s an example of how to do this in your configuration file:\n",
+    "```\n",
+    "aad_config = {\n",
+    "    \"client_id\": \"YOUR_CLIENT_ID\",\n",
+    "    \"tenant_id\": \"YOUR_TENANT_ID\",\n",
+    "    \"authority\": \"https://login.microsoftonline.com/YOUR_TENANT_ID\",\n",
+    "    \"scope\": [\"https://graph.microsoft.com/.default\"],\n",
+    "}\n",
+    "```\n",
+    "#### Step 5: Authenticate and Acquire Tokens\n",
+    "Use the following code to authenticate and acquire tokens:\n",
+    "\n",
+    "```\n",
+    "from msal import ConfidentialClientApplication\n",
+    "\n",
+    "app = ConfidentialClientApplication(\n",
+    "    client_id=aad_config[\"client_id\"],\n",
+    "    client_credential=\"YOUR_CLIENT_SECRET\",\n",
+    "    authority=aad_config[\"authority\"]\n",
+    ")\n",
+    "\n",
+    "result = app.acquire_token_for_client(scopes=aad_config[\"scope\"])\n",
+    "\n",
+    "if \"access_token\" in result:\n",
+    "    print(\"Token acquired\")\n",
+    "else:\n",
+    "    print(\"Error acquiring token:\", result.get(\"error\"))\n",
+    "```\n",
+    "\n",
+    "For more details, refer to the [Authenticate and authorize in Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/api-management/api-management-authenticate-authorize-azure-openai) and [How to configure Azure OpenAI Service with Microsoft Entra ID authentication](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/managed-identity).\n",
+    "\n",
+    "\n",
+    "#### Step 6: Configure Azure OpenAI with AAD Auth in AutoGen\n",
+    "To use AAD authentication with Azure OpenAI in AutoGen, configure the `llm_config` with the necessary parameters.\n",
+    "\n",
+    "Here is an example configuration:\n",
+    "\n",
+    "```\n",
+    "llm_config = {\n",
+    "    \"config_list\": [\n",
+    "        {\n",
+    "            \"model\": \"gpt-4\",\n",
+    "            \"base_url\": \"YOUR_BASE_URL\",\n",
+    "            \"api_type\": \"azure\",\n",
+    "            \"api_version\": \"2024-02-01\",\n",
+    "            \"max_tokens\": 1000,\n",
+    "            \"azure_ad_token_provider\": \"DEFAULT\"\n",
+    "        }\n",
+    "    ]\n",
+    "}\n",
+    "```\n",
+    "\n",
+    "For more details, refer to the [Authenticate and authorize in Azure OpenAI Service](https://learn.microsoft.com/en-us/azure/api-management/api-management-authenticate-authorize-azure-openai) and [How to configure Azure OpenAI Service with Microsoft Entra ID authentication](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/managed-identity).\n",
+    "\n",
+    "In this configuration:\n",
+    "- `model`: The Azure OpenAI deployment name.\n",
+    "- `base_url`: The base URL of the Azure OpenAI endpoint.\n",
+    "- `api_type`: Should be set to \"azure\".\n",
+    "- `api_version`: The API version to use.\n",
+    "- `azure_ad_token_provider`: Set to \"DEFAULT\" to use the default token provider.\n",
+    "\n",
+    "#### Example of Initializing an Assistant Agent with AAD Auth\n",
+    "```\n",
+    "import autogen\n",
+    "\n",
+    "# Initialize the assistant agent with the AAD authenticated config\n",
+    "assistant = autogen.AssistantAgent(name=\"assistant\", llm_config=llm_config)\n",
+    "```\n",
+    "\n",
+    "#### Troubleshooting\n",
+    "If you encounter issues, check the following:\n",
+    "- Ensure your `Client ID` and `Tenant ID` are correct.\n",
+    "- Verify the permissions granted to your application.\n",
+    "- Check network connectivity and Azure service status.\n",
+    "\n",
+    "This documentation provides a complete guide to configure and use AAD authentication with Azure OpenAI in the AutoGen.\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},