Skip to content

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.ipynb
index 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": {},