microsoft-agents-authentication-msal 0.6.1__py3-none-any.whl

microsoft_agents/authentication/msal/__init__.py

@@ -0,0 +1,7 @@
+from .msal_auth import MsalAuth
+from .msal_connection_manager import MsalConnectionManager
+
+__all__ = [
+    "MsalAuth",
+    "MsalConnectionManager",
+]

microsoft_agents/authentication/msal/errors/__init__.py

@@ -0,0 +1,15 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Error resources for Microsoft Agents Authentication MSAL package.
+"""
+
+from microsoft_agents.activity.errors import ErrorMessage
+
+from .error_resources import AuthenticationErrorResources
+
+# Singleton instance
+authentication_errors = AuthenticationErrorResources()
+
+__all__ = ["ErrorMessage", "AuthenticationErrorResources", "authentication_errors"]

microsoft_agents/authentication/msal/errors/error_resources.py

@@ -0,0 +1,67 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+"""
+Authentication error resources for Microsoft Agents SDK.
+
+Error codes are in the range -60000 to -60999.
+"""
+
+from microsoft_agents.activity.errors import ErrorMessage
+
+
+class AuthenticationErrorResources:
+    """
+    Error messages for authentication operations.
+
+    Error codes are organized in the range -60000 to -60999.
+    """
+
+    FailedToAcquireToken = ErrorMessage(
+        "Failed to acquire token. {0}",
+        -60012,
+    )
+
+    InvalidInstanceUrl = ErrorMessage(
+        "Invalid instance URL",
+        -60013,
+    )
+
+    OnBehalfOfFlowNotSupportedManagedIdentity = ErrorMessage(
+        "On-behalf-of flow is not supported with Managed Identity authentication.",
+        -60014,
+    )
+
+    OnBehalfOfFlowNotSupportedAuthType = ErrorMessage(
+        "On-behalf-of flow is not supported with the current authentication type: {0}",
+        -60015,
+    )
+
+    AuthenticationTypeNotSupported = ErrorMessage(
+        "Authentication type not supported",
+        -60016,
+    )
+
+    AgentApplicationInstanceIdRequired = ErrorMessage(
+        "Agent application instance Id must be provided.",
+        -60017,
+    )
+
+    FailedToAcquireAgenticInstanceToken = ErrorMessage(
+        "Failed to acquire agentic instance token or agent token for agent_app_instance_id {0}",
+        -60018,
+    )
+
+    AgentApplicationInstanceIdAndUserIdRequired = ErrorMessage(
+        "Agent application instance Id and agentic user Id must be provided.",
+        -60019,
+    )
+
+    FailedToAcquireInstanceOrAgentToken = ErrorMessage(
+        "Failed to acquire instance token or agent token for agent_app_instance_id {0} and agentic_user_id {1}",
+        -60020,
+    )
+
+    def __init__(self):
+        """Initialize AuthenticationErrorResources."""
+        pass

microsoft_agents/authentication/msal/msal_auth.py

@@ -0,0 +1,442 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import jwt
+from typing import Optional
+from urllib.parse import urlparse, ParseResult as URI
+from msal import (
+    ConfidentialClientApplication,
+    ManagedIdentityClient,
+    UserAssignedManagedIdentity,
+    SystemAssignedManagedIdentity,
+)
+from requests import Session
+from cryptography.x509 import load_pem_x509_certificate
+from cryptography.hazmat.backends import default_backend
+from cryptography.hazmat.primitives import hashes
+
+from microsoft_agents.activity._utils import _DeferredString
+
+from microsoft_agents.hosting.core import (
+    AuthTypes,
+    AccessTokenProviderBase,
+    AgentAuthConfiguration,
+)
+from microsoft_agents.authentication.msal.errors import authentication_errors
+
+logger = logging.getLogger(__name__)
+
+
+async def _async_acquire_token_for_client(msal_auth_client, *args, **kwargs):
+    """MSAL in Python does not support async, so we use asyncio.to_thread to run it in
+    a separate thread and avoid blocking the event loop
+    """
+    return await asyncio.to_thread(
+        lambda: msal_auth_client.acquire_token_for_client(*args, **kwargs)
+    )
+
+
+class MsalAuth(AccessTokenProviderBase):
+
+    _client_credential_cache = None
+
+    def __init__(self, msal_configuration: AgentAuthConfiguration):
+        """Initializes the MsalAuth class with the given configuration.
+
+        :param msal_configuration: The MSAL authentication configuration. Assumed to
+            not be mutated after being passed in.
+        :type msal_configuration: :class:`microsoft_agents.hosting.core.authorization.agent_auth_configuration.AgentAuthConfiguration`
+        """
+
+        self._msal_configuration = msal_configuration
+        self._msal_auth_client = None
+        logger.debug(
+            f"Initializing MsalAuth with configuration: {self._msal_configuration}"
+        )
+
+    async def get_access_token(
+        self, resource_url: str, scopes: list[str], force_refresh: bool = False
+    ) -> str:
+        logger.debug(
+            f"Requesting access token for resource: {resource_url}, scopes: {scopes}"
+        )
+        valid_uri, instance_uri = self._uri_validator(resource_url)
+        if not valid_uri:
+            raise ValueError(str(authentication_errors.InvalidInstanceUrl))
+
+        local_scopes = self._resolve_scopes_list(instance_uri, scopes)
+        self._create_client_application()
+
+        if isinstance(self._msal_auth_client, ManagedIdentityClient):
+            logger.info("Acquiring token using Managed Identity Client.")
+            auth_result_payload = await _async_acquire_token_for_client(
+                self._msal_auth_client, resource=resource_url
+            )
+        elif isinstance(self._msal_auth_client, ConfidentialClientApplication):
+            logger.info("Acquiring token using Confidential Client Application.")
+            auth_result_payload = await _async_acquire_token_for_client(
+                self._msal_auth_client, scopes=local_scopes
+            )
+        else:
+            auth_result_payload = None
+
+        res = auth_result_payload.get("access_token") if auth_result_payload else None
+        if not res:
+            logger.error("Failed to acquire token for resource %s", auth_result_payload)
+            raise ValueError(
+                authentication_errors.FailedToAcquireToken.format(
+                    str(auth_result_payload)
+                )
+            )
+
+        return res
+
+    async def acquire_token_on_behalf_of(
+        self, scopes: list[str], user_assertion: str
+    ) -> str:
+        """
+        Acquire a token on behalf of a user.
+        :param scopes: The scopes for which to get the token.
+        :param user_assertion: The user assertion token.
+        :return: The access token as a string.
+        """
+
+        self._create_client_application()
+        if isinstance(self._msal_auth_client, ManagedIdentityClient):
+            logger.error(
+                "Attempted on-behalf-of flow with Managed Identity authentication."
+            )
+            raise NotImplementedError(
+                str(authentication_errors.OnBehalfOfFlowNotSupportedManagedIdentity)
+            )
+        elif isinstance(self._msal_auth_client, ConfidentialClientApplication):
+            # TODO: Handling token error / acquisition failed
+
+            # MSAL in Python does not support async, so we use asyncio.to_thread to run it in
+            # a separate thread and avoid blocking the event loop
+            token = await asyncio.to_thread(
+                lambda: self._msal_auth_client.acquire_token_on_behalf_of(
+                    scopes=scopes, user_assertion=user_assertion
+                )
+            )
+
+            if "access_token" not in token:
+                logger.error(
+                    f"Failed to acquire token on behalf of user: {user_assertion}"
+                )
+                raise ValueError(
+                    authentication_errors.FailedToAcquireToken.format(str(token))
+                )
+
+            return token["access_token"]
+
+        logger.error(
+            f"On-behalf-of flow is not supported with the current authentication type: {self._msal_auth_client.__class__.__name__}"
+        )
+        raise NotImplementedError(
+            authentication_errors.OnBehalfOfFlowNotSupportedAuthType.format(
+                self._msal_auth_client.__class__.__name__
+            )
+        )
+
+    def _create_client_application(self) -> None:
+
+        if self._msal_auth_client:
+            return
+
+        if self._msal_configuration.AUTH_TYPE == AuthTypes.user_managed_identity:
+            self._msal_auth_client = ManagedIdentityClient(
+                UserAssignedManagedIdentity(
+                    client_id=self._msal_configuration.CLIENT_ID
+                ),
+                http_client=Session(),
+            )
+
+        elif self._msal_configuration.AUTH_TYPE == AuthTypes.system_managed_identity:
+            self._msal_auth_client = ManagedIdentityClient(
+                SystemAssignedManagedIdentity(),
+                http_client=Session(),
+            )
+        else:
+            authority_path = self._msal_configuration.TENANT_ID or "botframework.com"
+            authority = f"https://login.microsoftonline.com/{authority_path}"
+
+            if self._client_credential_cache:
+                logger.info("Using cached client credentials for MSAL authentication.")
+                pass
+            elif self._msal_configuration.AUTH_TYPE == AuthTypes.client_secret:
+                self._client_credential_cache = self._msal_configuration.CLIENT_SECRET
+            elif self._msal_configuration.AUTH_TYPE == AuthTypes.certificate:
+                with open(self._msal_configuration.CERT_KEY_FILE) as file:
+                    logger.info(
+                        "Loading certificate private key for MSAL authentication."
+                    )
+                    private_key = file.read()
+
+                with open(self._msal_configuration.CERT_PEM_FILE) as file:
+                    logger.info("Loading public certificate for MSAL authentication.")
+                    public_certificate = file.read()
+
+                # Create an X509 object and calculate the thumbprint
+                logger.info("Calculating thumbprint for the public certificate.")
+                cert = load_pem_x509_certificate(
+                    data=bytes(public_certificate, "UTF-8"), backend=default_backend()
+                )
+                thumbprint = cert.fingerprint(hashes.SHA1()).hex()
+
+                self._client_credential_cache = {
+                    "thumbprint": thumbprint,
+                    "private_key": private_key,
+                }
+            else:
+                logger.error(
+                    f"Unsupported authentication type: {self._msal_configuration.AUTH_TYPE}"
+                )
+                raise NotImplementedError(
+                    str(authentication_errors.AuthenticationTypeNotSupported)
+                )
+
+            self._msal_auth_client = ConfidentialClientApplication(
+                client_id=self._msal_configuration.CLIENT_ID,
+                authority=authority,
+                client_credential=self._client_credential_cache,
+            )
+
+    @staticmethod
+    def _uri_validator(url_str: str) -> tuple[bool, Optional[URI]]:
+        try:
+            result = urlparse(url_str)
+            return all([result.scheme, result.netloc]), result
+        except AttributeError:
+            logger.error(f"URI parsing error for {url_str}")
+            return False, None
+
+    def _resolve_scopes_list(self, instance_url: URI, scopes=None) -> list[str]:
+        if scopes:
+            return scopes
+
+        temp_list: list[str] = []
+        for scope in self._msal_configuration.SCOPES:
+            scope_placeholder = scope
+            if "{instance}" in scope_placeholder.lower():
+                scope_placeholder = scope_placeholder.replace(
+                    "{instance}", f"{instance_url.scheme}://{instance_url.hostname}"
+                )
+            temp_list.append(scope_placeholder)
+        logger.debug(f"Resolved scopes: {temp_list}")
+        return temp_list
+
+    # the call to MSAL is blocking, but in the future we want to create an asyncio task
+    # to avoid this
+    async def get_agentic_application_token(
+        self, agent_app_instance_id: str
+    ) -> Optional[str]:
+        """Gets the agentic application token for the given agent application instance ID.
+
+        :param agent_app_instance_id: The agent application instance ID.
+        :type agent_app_instance_id: str
+        :return: The agentic application token, or None if not found.
+        :rtype: Optional[str]
+        """
+
+        if not agent_app_instance_id:
+            raise ValueError(
+                str(authentication_errors.AgentApplicationInstanceIdRequired)
+            )
+
+        logger.info(
+            "Attempting to get agentic application token from agent_app_instance_id %s",
+            agent_app_instance_id,
+        )
+        self._create_client_application()
+
+        if isinstance(self._msal_auth_client, ConfidentialClientApplication):
+
+            # https://github.dev/AzureAD/microsoft-authentication-library-for-dotnet
+            auth_result_payload = await _async_acquire_token_for_client(
+                self._msal_auth_client,
+                ["api://AzureAdTokenExchange/.default"],
+                data={"fmi_path": agent_app_instance_id},
+            )
+
+            if auth_result_payload:
+                return auth_result_payload.get("access_token")
+
+        return None
+
+    async def get_agentic_instance_token(
+        self, agent_app_instance_id: str
+    ) -> tuple[str, str]:
+        """Gets the agentic instance token for the given agent application instance ID.
+
+        :param agent_app_instance_id: The agent application instance ID.
+        :type agent_app_instance_id: str
+        :return: A tuple containing the agentic instance token and the agent application token.
+        :rtype: tuple[str, str]
+        """
+
+        if not agent_app_instance_id:
+            raise ValueError(
+                str(authentication_errors.AgentApplicationInstanceIdRequired)
+            )
+
+        logger.info(
+            "Attempting to get agentic instance token from agent_app_instance_id %s",
+            agent_app_instance_id,
+        )
+        agent_token_result = await self.get_agentic_application_token(
+            agent_app_instance_id
+        )
+
+        if not agent_token_result:
+            logger.error(
+                "Failed to acquire agentic instance token or agent token for agent_app_instance_id %s",
+                agent_app_instance_id,
+            )
+            raise Exception(
+                authentication_errors.FailedToAcquireAgenticInstanceToken.format(
+                    agent_app_instance_id
+                )
+            )
+
+        authority = (
+            f"https://login.microsoftonline.com/{self._msal_configuration.TENANT_ID}"
+        )
+
+        instance_app = ConfidentialClientApplication(
+            client_id=agent_app_instance_id,
+            authority=authority,
+            client_credential={"client_assertion": agent_token_result},
+        )
+
+        agentic_instance_token = await _async_acquire_token_for_client(
+            instance_app, ["api://AzureAdTokenExchange/.default"]
+        )
+
+        if not agentic_instance_token:
+            logger.error(
+                "Failed to acquire agentic instance token or agent token for agent_app_instance_id %s",
+                agent_app_instance_id,
+            )
+            raise Exception(
+                authentication_errors.FailedToAcquireAgenticInstanceToken.format(
+                    agent_app_instance_id
+                )
+            )
+
+        # future scenario where we don't know the blueprint id upfront
+
+        token = agentic_instance_token.get("access_token")
+        if not token:
+            logger.error(
+                "Failed to acquire agentic instance token, %s", agentic_instance_token
+            )
+            raise ValueError(
+                authentication_errors.FailedToAcquireToken.format(
+                    str(agentic_instance_token)
+                )
+            )
+
+        logger.debug(
+            "Agentic blueprint id: %s",
+            _DeferredString(
+                lambda: jwt.decode(token, options={"verify_signature": False}).get(
+                    "xms_par_app_azp"
+                )
+            ),
+        )
+
+        return agentic_instance_token["access_token"], agent_token_result
+
+    async def get_agentic_user_token(
+        self, agent_app_instance_id: str, agentic_user_id: str, scopes: list[str]
+    ) -> Optional[str]:
+        """Gets the agentic user token for the given agent application instance ID and agentic user Id and the scopes.
+
+        :param agent_app_instance_id: The agent application instance ID.
+        :type agent_app_instance_id: str
+        :param agentic_user_id: The agentic user ID.
+        :type agentic_user_id: str
+        :param scopes: The scopes to request for the token.
+        :type scopes: list[str]
+        :return: The agentic user token, or None if not found.
+        :rtype: Optional[str]
+        """
+        if not agent_app_instance_id or not agentic_user_id:
+            raise ValueError(
+                str(authentication_errors.AgentApplicationInstanceIdAndUserIdRequired)
+            )
+
+        logger.info(
+            "Attempting to get agentic user token from agent_app_instance_id %s and agentic_user_id %s",
+            agent_app_instance_id,
+            agentic_user_id,
+        )
+        instance_token, agent_token = await self.get_agentic_instance_token(
+            agent_app_instance_id
+        )
+
+        if not instance_token or not agent_token:
+            logger.error(
+                "Failed to acquire instance token or agent token for agent_app_instance_id %s and agentic_user_id %s",
+                agent_app_instance_id,
+                agentic_user_id,
+            )
+            raise Exception(
+                authentication_errors.FailedToAcquireInstanceOrAgentToken.format(
+                    agent_app_instance_id, agentic_user_id
+                )
+            )
+
+        authority = (
+            f"https://login.microsoftonline.com/{self._msal_configuration.TENANT_ID}"
+        )
+
+        instance_app = ConfidentialClientApplication(
+            client_id=agent_app_instance_id,
+            authority=authority,
+            client_credential={"client_assertion": agent_token},
+        )
+
+        logger.info(
+            "Acquiring agentic user token for agent_app_instance_id %s and agentic_user_id %s",
+            agent_app_instance_id,
+            agentic_user_id,
+        )
+        # MSAL in Python does not support async, so we use asyncio.to_thread to run it in
+        # a separate thread and avoid blocking the event loop
+        auth_result_payload = await _async_acquire_token_for_client(
+            instance_app,
+            scopes,
+            data={
+                "user_id": agentic_user_id,
+                "user_federated_identity_credential": instance_token,
+                "grant_type": "user_fic",
+            },
+        )
+
+        if not auth_result_payload:
+            logger.error(
+                "Failed to acquire agentic user token for agent_app_instance_id %s and agentic_user_id %s, %s",
+                agent_app_instance_id,
+                agentic_user_id,
+                auth_result_payload,
+            )
+            return None
+
+        access_token = auth_result_payload.get("access_token")
+        if not access_token:
+            logger.error(
+                "Failed to acquire agentic user token for agent_app_instance_id %s and agentic_user_id %s, %s",
+                agent_app_instance_id,
+                agentic_user_id,
+                auth_result_payload,
+            )
+            return None
+
+        logger.info("Acquired agentic user token response.")
+        return access_token

microsoft_agents/authentication/msal/msal_connection_manager.py

@@ -0,0 +1,140 @@
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License.
+
+import re
+from typing import Dict, List, Optional
+from microsoft_agents.hosting.core import (
+    AgentAuthConfiguration,
+    AccessTokenProviderBase,
+    ClaimsIdentity,
+    Connections,
+)
+
+from .msal_auth import MsalAuth
+
+
+class MsalConnectionManager(Connections):
+    _connections: Dict[str, MsalAuth]
+    _connections_map: List[Dict[str, str]]
+    _service_connection_configuration: AgentAuthConfiguration
+
+    def __init__(
+        self,
+        connections_configurations: Optional[Dict[str, AgentAuthConfiguration]] = None,
+        connections_map: Optional[List[Dict[str, str]]] = None,
+        **kwargs,
+    ):
+        """
+        Initialize the MSAL connection manager.
+
+        :arg connections_configurations: A dictionary of connection configurations.
+        :type connections_configurations: Dict[str, :class:`microsoft_agents.hosting.core.AgentAuthConfiguration`]
+        :arg connections_map: A list of connection mappings.
+        :type connections_map: List[Dict[str, str]]
+        :raises ValueError: If no service connection configuration is provided.
+        """
+
+        self._connections: Dict[str, MsalAuth] = {}
+        self._connections_map = connections_map or kwargs.get("CONNECTIONSMAP", {})
+        self._service_connection_configuration: AgentAuthConfiguration = None
+
+        if connections_configurations:
+            for (
+                connection_name,
+                connection_settings,
+            ) in connections_configurations.items():
+                self._connections[connection_name] = MsalAuth(
+                    AgentAuthConfiguration(**connection_settings)
+                )
+        else:
+            raw_configurations: Dict[str, Dict] = kwargs.get("CONNECTIONS", {})
+            for connection_name, connection_settings in raw_configurations.items():
+                parsed_configuration = AgentAuthConfiguration(
+                    **connection_settings.get("SETTINGS", {})
+                )
+                self._connections[connection_name] = MsalAuth(parsed_configuration)
+                if connection_name == "SERVICE_CONNECTION":
+                    self._service_connection_configuration = parsed_configuration
+
+        if not self._connections.get("SERVICE_CONNECTION", None):
+            raise ValueError("No service connection configuration provided.")
+
+    def get_connection(self, connection_name: Optional[str]) -> AccessTokenProviderBase:
+        """
+        Get the OAuth connection for the agent.
+
+        :arg connection_name: The name of the connection.
+        :type connection_name: Optional[str]
+        :return: The OAuth connection for the agent.
+        :rtype: :class:`microsoft_agents.hosting.core.AccessTokenProviderBase`
+        """
+        # should never be None
+        return self._connections.get(connection_name, None)
+
+    def get_default_connection(self) -> AccessTokenProviderBase:
+        """
+        Get the default OAuth connection for the agent.
+
+        :return: The default OAuth connection for the agent.
+        :rtype: :class:`microsoft_agents.hosting.core.AccessTokenProviderBase`
+        """
+        # should never be None
+        return self._connections.get("SERVICE_CONNECTION", None)
+
+    def get_token_provider(
+        self, claims_identity: ClaimsIdentity, service_url: str
+    ) -> AccessTokenProviderBase:
+        """
+        Get the OAuth token provider for the agent.
+
+        :arg claims_identity: The claims identity of the bot.
+        :type claims_identity: :class:`microsoft_agents.hosting.core.ClaimsIdentity`
+        :arg service_url: The service URL of the bot.
+        :type service_url: str
+        :return: The OAuth token provider for the agent.
+        :rtype: :class:`microsoft_agents.hosting.core.AccessTokenProviderBase`
+        :raises ValueError: If no connection is found for the given audience and service URL.
+        """
+        if not claims_identity or not service_url:
+            raise ValueError(
+                "Claims identity and Service URL are required to get the token provider."
+            )
+
+        if not self._connections_map:
+            return self.get_default_connection()
+
+        aud = claims_identity.get_app_id() or ""
+        for item in self._connections_map:
+            audience_match = True
+            item_aud = item.get("AUDIENCE", "")
+            if item_aud:
+                audience_match = item_aud.lower() == aud.lower()
+
+            if audience_match:
+                item_service_url = item.get("SERVICEURL", "")
+                if item_service_url == "*" or item_service_url == "":
+                    connection_name = item.get("CONNECTION")
+                    connection = self.get_connection(connection_name)
+                    if connection:
+                        return connection
+
+                else:
+                    res = re.match(item_service_url, service_url, re.IGNORECASE)
+                    if res:
+                        connection_name = item.get("CONNECTION")
+                        connection = self.get_connection(connection_name)
+                        if connection:
+                            return connection
+
+        raise ValueError(
+            f"No connection found for audience '{aud}' and serviceUrl '{service_url}'."
+        )
+
+    def get_default_connection_configuration(self) -> AgentAuthConfiguration:
+        """
+        Get the default connection configuration for the agent.
+
+        :return: The default connection configuration for the agent.
+        :rtype: :class:`microsoft_agents.hosting.core.AgentAuthConfiguration`
+        """
+        return self._service_connection_configuration

microsoft_agents_authentication_msal-0.6.1.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: microsoft-agents-authentication-msal
+Version: 0.6.1
+Summary: A msal-based authentication library for Microsoft Agents
+Author: Microsoft Corporation
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/microsoft/Agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: microsoft-agents-hosting-core==0.6.1
+Requires-Dist: msal>=1.31.1
+Requires-Dist: requests>=2.32.3
+Requires-Dist: cryptography>=44.0.0
+Dynamic: license-file
+Dynamic: requires-dist
+
+# Microsoft Agents MSAL Authentication
+
+[![PyPI version](https://img.shields.io/pypi/v/microsoft-agents-authentication-msal)](https://pypi.org/project/microsoft-agents-authentication-msal/)
+
+Provides secure authentication for your agents using Microsoft Authentication Library (MSAL). It handles getting tokens from Azure AD so your agent can securely communicate with Microsoft services like Teams, Graph API, and other Azure resources.
+
+# What is this?
+
+This library is part of the **Microsoft 365 Agents SDK for Python** - a comprehensive framework for building enterprise-grade conversational AI agents. The SDK enables developers to create intelligent agents that work across multiple platforms including Microsoft Teams, M365 Copilot, Copilot Studio, and web chat, with support for third-party integrations like Slack, Facebook Messenger, and Twilio.
+
+## Release Notes
+<table style="width:100%">
+  <tr>
+    <th style="width:20%">Version</th>
+    <th style="width:20%">Date</th>
+    <th style="width:60%">Release Notes</th>
+  </tr>
+  <tr>
+    <td>0.5.0</td>
+    <td>2025-10-22</td>
+    <td>
+      <a href="https://github.com/microsoft/Agents-for-python/blob/main/changelog.md">
+        0.5.0 Release Notes
+      </a>
+    </td>
+  </tr>
+</table>
+
+## Packages Overview
+
+We offer the following PyPI packages to create conversational experiences based on Agents:
+
+| Package Name | PyPI Version | Description |
+|--------------|-------------|-------------|
+| `microsoft-agents-activity` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-activity)](https://pypi.org/project/microsoft-agents-activity/) | Types and validators implementing the Activity protocol spec. |
+| `microsoft-agents-hosting-core` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-hosting-core)](https://pypi.org/project/microsoft-agents-hosting-core/) | Core library for Microsoft Agents hosting. |
+| `microsoft-agents-hosting-aiohttp` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-hosting-aiohttp)](https://pypi.org/project/microsoft-agents-hosting-aiohttp/) | Configures aiohttp to run the Agent. |
+| `microsoft-agents-hosting-teams` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-hosting-teams)](https://pypi.org/project/microsoft-agents-hosting-teams/) | Provides classes to host an Agent for Teams. |
+| `microsoft-agents-storage-blob` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-storage-blob)](https://pypi.org/project/microsoft-agents-storage-blob/) | Extension to use Azure Blob as storage. |
+| `microsoft-agents-storage-cosmos` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-storage-cosmos)](https://pypi.org/project/microsoft-agents-storage-cosmos/) | Extension to use CosmosDB as storage. |
+| `microsoft-agents-authentication-msal` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-authentication-msal)](https://pypi.org/project/microsoft-agents-authentication-msal/) | MSAL-based authentication for Microsoft Agents. |
+
+Additionally we provide a Copilot Studio Client, to interact with Agents created in CopilotStudio:
+
+| Package Name | PyPI Version | Description |
+|--------------|-------------|-------------|
+| `microsoft-agents-copilotstudio-client` | [![PyPI](https://img.shields.io/pypi/v/microsoft-agents-copilotstudio-client)](https://pypi.org/project/microsoft-agents-copilotstudio-client/) | Direct to Engine client to interact with Agents created in CopilotStudio |
+
+## Installation
+
+```bash
+pip install microsoft-agents-authentication-msal
+```
+
+## Quick Start
+
+### Basic Setup with Client Secret
+
+Define your client secrets in the ENV file
+```python
+CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=client-id
+CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=client-secret
+CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=tenant-id
+```
+
+Load the Configuration (Code from [main.py Quickstart Sample](https://github.com/microsoft/Agents/blob/main/samples/python/quickstart/src/main.py))
+
+```python
+from .start_server import start_server
+
+start_server(
+    agent_application=AGENT_APP,
+    auth_configuration=CONNECTION_MANAGER.get_default_connection_configuration(),
+)
+```
+Then start the Agent (code snipped from (start_server.py Quickstart Sample](https://github.com/microsoft/Agents/blob/main/samples/python/quickstart/src/start_server.py)):
+
+```python
+def start_server(
+    agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
+):
+    async def entry_point(req: Request) -> Response:
+        agent: AgentApplication = req.app["agent_app"]
+        adapter: CloudAdapter = req.app["adapter"]
+        return await start_agent_process(
+            req,
+            agent,
+            adapter,
+        )
+[...]
+```
+
+## Authentication Types
+The M365 Agents SDK in Python supports the following Auth types:
+```python
+class AuthTypes(str, Enum):
+    certificate = "certificate"
+    certificate_subject_name = "CertificateSubjectName"
+    client_secret = "ClientSecret"
+    user_managed_identity = "UserManagedIdentity"
+    system_managed_identity = "SystemManagedIdentity"
+```
+
+## Key Classes
+
+- **`MsalAuth`** - Core authentication provider using MSAL
+- **`MsalConnectionManager`** - Manages multiple authentication connections
+
+## Features
+
+✅ **Multiple auth types** - Client secret, certificate, managed identity  
+✅ **Token caching** - Automatic token refresh and caching  
+✅ **Multi-tenant** - Support for different Azure AD tenants  
+✅ **Agent-to-agent** - Secure communication between agents  
+✅ **On-behalf-of** - Act on behalf of users  
+
+# Security Best Practices
+
+- Store secrets in Azure Key Vault or environment variables
+- Use managed identities when possible (no secrets to manage)
+- Regularly rotate client secrets and certificates
+- Use least-privilege principle for scopes and permissions
+
+# Quick Links
+
+- 📦 [All SDK Packages on PyPI](https://pypi.org/search/?q=microsoft-agents)
+- 📖 [Complete Documentation](https://aka.ms/agents)
+- 💡 [Python Samples Repository](https://github.com/microsoft/Agents/tree/main/samples/python)
+- 🐛 [Report Issues](https://github.com/microsoft/Agents-for-python/issues)
+
+# Sample Applications
+Explore working examples in the [Python samples repository](https://github.com/microsoft/Agents/tree/main/samples/python):
+
+|Name|Description|README|
+|----|----|----|
+|Quickstart|Simplest agent|[Quickstart](https://github.com/microsoft/Agents/blob/main/samples/python/quickstart/README.md)|
+|Auto Sign In|Simple OAuth agent using Graph and GitHub|[auto-signin](https://github.com/microsoft/Agents/blob/main/samples/python/auto-signin/README.md)|
+|OBO Authorization|OBO flow to access a Copilot Studio Agent|[obo-authorization](https://github.com/microsoft/Agents/blob/main/samples/python/obo-authorization/README.md)|
+|Semantic Kernel Integration|A weather agent built with Semantic Kernel|[semantic-kernel-multiturn](https://github.com/microsoft/Agents/blob/main/samples/python/semantic-kernel-multiturn/README.md)|
+|Streaming Agent|Streams OpenAI responses|[azure-ai-streaming](https://github.com/microsoft/Agents/blob/main/samples/python/azureai-streaming/README.md)|
+|Copilot Studio Client|Console app to consume a Copilot Studio Agent|[copilotstudio-client](https://github.com/microsoft/Agents/blob/main/samples/python/copilotstudio-client/README.md)|
+|Cards Agent|Agent that uses rich cards to enhance conversation design |[cards](https://github.com/microsoft/Agents/blob/main/samples/python/cards/README.md)|

microsoft_agents_authentication_msal-0.6.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+microsoft_agents/authentication/msal/__init__.py,sha256=hjPpakL4zyqeCTEBOUCcHaRnSpG80q-L0csG5HMalYI,151
+microsoft_agents/authentication/msal/msal_auth.py,sha256=iWXAFYYv0MoxK_mvuRq_cren8fJZWrBbW7hsSGmTDLQ,17057
+microsoft_agents/authentication/msal/msal_connection_manager.py,sha256=v7o0ONzjId1G6Ta7IjHc1NtSeM3NWH4t7YilrwJzvYg,5713
+microsoft_agents/authentication/msal/errors/__init__.py,sha256=9dbI_fGa0J4-qq6mTwdAIjaDADDFypenn4ZcsK-F4nE,449
+microsoft_agents/authentication/msal/errors/error_resources.py,sha256=BIZNjhKLNZmyggblBkyQ3R2pGq3VkllEoni6QgBI4hw,1849
+microsoft_agents_authentication_msal-0.6.1.dist-info/licenses/LICENSE,sha256=ws_MuBL-SCEBqPBFl9_FqZkaaydIJmxHrJG2parhU4M,1141
+microsoft_agents_authentication_msal-0.6.1.dist-info/METADATA,sha256=BEbmKel2DbB7kq74vcPcrfFqEpYiwnZz2tOnunwm8PQ,8363
+microsoft_agents_authentication_msal-0.6.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+microsoft_agents_authentication_msal-0.6.1.dist-info/top_level.txt,sha256=lWKcT4v6fTA_NgsuHdNvuMjSrkiBMXohn64ApY7Xi8A,17
+microsoft_agents_authentication_msal-0.6.1.dist-info/RECORD,,

microsoft_agents_authentication_msal-0.6.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

microsoft_agents_authentication_msal-0.6.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

microsoft_agents_authentication_msal-0.6.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+microsoft_agents