{"id":9939,"library":"microsoft-agents-authentication-msal","title":"Microsoft Agents MSAL Authentication","description":"microsoft-agents-authentication-msal is a Python library providing MSAL-based authentication specifically for Microsoft Agents. It primarily implements the device code flow using MSAL to acquire authentication tokens. Currently at version 0.9.0, it's part of the broader Microsoft Agents framework and follows its release cadence, focusing on integrating with Microsoft services.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/microsoft/Agents","tags":["microsoft","azure","msal","authentication","agents","device-code-flow"],"install":[{"cmd":"pip install microsoft-agents-authentication-msal","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides the IAuthentication interface that this library implements.","package":"microsoft-agents-authentication"},{"reason":"The core Microsoft Authentication Library (MSAL) that this package wraps.","package":"msal"}],"imports":[{"note":"The top-level package name does not match the internal module path. Always import from `agents.auth.msal`.","wrong":"from microsoft_agents_authentication_msal import MSALAuthentication","symbol":"MSALAuthentication","correct":"from agents.auth.msal import MSALAuthentication"}],"quickstart":{"code":"import os\nfrom agents.auth.msal import MSALAuthentication\nfrom agents.auth.types import IAuthentication\n\n# For demonstration, retrieve client_id from environment variable.\n# In a real application, you would configure this securely.\nCLIENT_ID = os.environ.get('MSAL_CLIENT_ID', 'YOUR_MSAL_CLIENT_ID_HERE')\nif CLIENT_ID == 'YOUR_MSAL_CLIENT_ID_HERE':\n    print(\"WARNING: Please set the MSAL_CLIENT_ID environment variable or replace 'YOUR_MSAL_CLIENT_ID_HERE' with your actual Azure AD application client ID.\")\n\ntry:\n    # Initialize MSAL authentication using Device Code Flow\n    # This will print a URL and a device code that the user needs to enter in a browser.\n    auth: IAuthentication = MSALAuthentication(client_id=CLIENT_ID)\n\n    print(f\"Attempting to get token with client_id: {CLIENT_ID}...\")\n    # Acquire a token for Microsoft Graph default scope\n    # The actual scope might vary depending on the Microsoft Agent's requirements.\n    # Common scopes include \"https://graph.microsoft.com/.default\" for broad Graph access.\n    # Other scopes like \"api://<your-app-id>/.default\" might be used for custom APIs.\n    token_response = auth.get_token(scope=[\"https://graph.microsoft.com/.default\"])\n\n    print(\"\\nAuthentication successful!\")\n    print(f\"Access Token (first 20 chars): {token_response.access_token[:20]}...\")\n    print(f\"Expires On: {token_response.expires_on}\")\n\nexcept ValueError as e:\n    print(f\"Error during authentication setup: {e}\")\n    if \"client_id\" in str(e):\n        print(\"Hint: Ensure MSAL_CLIENT_ID is correctly set and not empty.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred during token acquisition: {e}\")\n    print(\"Please check your network connection, client_id, and ensure you completed the device code flow in the browser.\")","lang":"python","description":"Demonstrates basic authentication using the MSAL Device Code Flow. It initializes `MSALAuthentication` with a client ID and attempts to acquire an access token for the Microsoft Graph default scope. Note that this flow requires user interaction in a web browser."},"warnings":[{"fix":"Ensure your Python environment is version 3.10 or higher. Use `python --version` to check.","message":"This library requires Python 3.10 or newer. Installing with older Python versions will lead to dependency resolution errors or runtime issues.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `from agents.auth.msal import MSALAuthentication` as the correct import path, matching the internal module structure.","message":"The import path `from microsoft_agents_authentication_msal import MSALAuthentication` is incorrect and will result in a `ModuleNotFoundError`.","severity":"breaking","affected_versions":"All versions"},{"fix":"Be prepared for the application to print a URL and a code. The user must navigate to the URL, enter the code, and complete authentication in their browser. This flow is not suitable for fully automated, headless environments without specific MSAL configuration.","message":"The `MSALAuthentication` class primarily implements the Device Code Flow, which requires user interaction in a web browser.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Register an application in Azure Active Directory (AAD), grant it the necessary API permissions (e.g., Microsoft Graph), and use its assigned Client ID. Ensure the application type supports public client flows for device code.","message":"A valid Azure AD application Client ID is essential for successful authentication. Using a placeholder or an invalid ID will cause errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change your import statement from `from microsoft_agents_authentication_msal import MSALAuthentication` to `from agents.auth.msal import MSALAuthentication`.","cause":"Attempting to import `MSALAuthentication` directly from the top-level package name (`microsoft_agents_authentication_msal`) instead of its internal module path.","error":"ModuleNotFoundError: No module named 'agents'"},{"fix":"Pass a valid Azure AD application client ID when initializing: `MSALAuthentication(client_id=\"YOUR_AZURE_AD_CLIENT_ID\")`. Ensure the client ID is not empty.","cause":"The `MSALAuthentication` constructor was called without providing a `client_id` argument, or it was an empty string.","error":"ValueError: Parameter 'client_id' is required."},{"fix":"Verify that your Azure AD application is configured with the correct API permissions and that an administrator or user has granted consent. For Device Code Flow, ensure 'Allow public client flows' is enabled under Authentication settings.","cause":"The Azure AD application lacks the necessary permissions, or user/admin consent has not been granted for the requested scopes.","error":"MsalServiceException: AADSTS65001: The user or administrator has not consented to use the application with ID '...' named '...'. Send an interactive authorization request for this user and resource."},{"fix":"Re-run the authentication process and ensure the user navigates to the provided URL, enters the device code, and completes the sign-in/consent steps promptly in their web browser.","cause":"The user did not complete the device code flow in the browser within the allowed time, or explicitly cancelled the authentication.","error":"UserCancelledError: Authentication cancelled by user."}]}