A programming framework for agentic AI
Fix Issue #2880: Document the usage of the AAD auth (#2941)
Prithvi56007d1164ec
diff --git a/website/docs/topics/llm_configuration.ipynb b/website/docs/topics/llm_configuration.ipynbindex f6f383cd8..0c094f653 100644--- 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": {},