[OPS Common SDK] Update Communication Common SDK for Teams Phone Extensibility GA (#41219)

* Update models.py

* Update models.py

* Update models.py

* Update phone number identifier

* add tests

* small updates

* Update test_identifier_raw_id.py

* Update test_identifier_raw_id.py

* Update test_identifier_raw_id.py

* Create entra_user_credential_async.py

* add entra token cred

* add async exchange

* Update models.py

* Update test_identifier_raw_id.py

* Update test_identifier_raw_id.py

* update credential

* Update entra_user_credential_async.py

* Update entra_user_credential_async.py

* Update entra_user_credential_async.py

* Update entra_user_credential_async.py

* Create pipeline_utils.py

* Create entra_token_guard_policy.py

* Create entra_token_credential_options.py

* Create token_exchange.py

* Update token_exchange.py

* updates

* Update token_exchange.py

* Update token_exchange.py

* cleanup old files

* Update token_exchange.py

* Update entra_token_guard_policy.py

* updated credential classes

* updates

* Delete manual_test.py

* Update user_credential.py

* Copy to all _shared in all sdks

* Update sdk/communication/azure-communication-callautomation/azure/communication/callautomation/_shared/entra_token_guard_policy.py

Co-authored-by: Dominik <dominik.messinger@gmail.com>

* Update token_exchange.py

* update version

* Fix imports

* Fix imports in all folders

* Fix test

* Update test_identifier_raw_id.py

* Update dev_requirements.txt

* try to fix conflict in pipeline

* try to fix conflict in pipeline 2

* Update setup.py

* try to fix call automation

* remove references

* expose the identifiers

* Update documentation for credential to include the optional params

* Delete manual_test.py

* Update _version.py

* fix comment to default the cloud

* fix comments for phone number properties

* fix path

* Update CHANGELOG.md

* fix cloud param

* fix comment

* Create test_entra_token_guard_policy.py

* fix for cloud param

* Add tests for token exchange

* add tests for credential

* update test

* Update test_user_credential_async.py

* add check in async cred

* fix cloud

* update not required

* Update test_identifier_raw_id.py

* fix passing scopes

* copy paste from identity

* fix space

* fix sending scopes

* Update test_token_exchange.py

* fix spaces for doc

* fix pylint errors

* fix pylint error in model

* fix props in phone number

* fix dateutil import

* update init of asserted_id

* replace none with ""

* update models phone number

* fix some pylint errors: format

* split files

* pylint fixes

* pylint call automation

* pylint for all

* fix some pylint warnings

* fix last warnings in identity

* update all

* update token exchange

* update credential for all sdks

* fix comments

* add some tests

* fix tests

* fix some comments

* fix comments

* copy in all sdks

* fix include

* fix import

* fix tests

* fix comments

* fix analysis warnings

* fix mypy

* fix pylint

* fix mypy

* fix optional scopes

---------

Co-authored-by: Dominik <dominik.messinger@gmail.com>

Author: cemateia

sdk/communication/azure-communication-callautomation/azure/communication/callautomation/__init__.py

@@ -38,6 +38,8 @@
     CommunicationIdentifierKind,
     CommunicationCloudEnvironment,
     UnknownIdentifier,
+    TeamsExtensionUserProperties,
+    TeamsExtensionUserIdentifier,
 )
 from ._generated.models._enums import (
     CallRejectReason,
@@ -93,6 +95,8 @@
     "CommunicationIdentifierKind",
     "CommunicationCloudEnvironment",
     "UnknownIdentifier",
+    "TeamsExtensionUserProperties",
+    "TeamsExtensionUserIdentifier",
 
     # enums
     "CallRejectReason",

sdk/communication/azure-communication-callautomation/azure/communication/callautomation/_shared/entra_token_guard_policy.py

@@ -0,0 +1,30 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+from azure.core.pipeline.policies import HTTPPolicy
+from azure.core.pipeline import PipelineRequest
+from . import token_utils
+
+
+class EntraTokenGuardPolicy(HTTPPolicy):
+    """A pipeline policy that caches the response for a given Entra token and reuses it if valid."""
+
+    def __init__(self):
+        super().__init__()
+        self._entra_token_cache = None
+        self._response_cache = None
+
+    def send(self, request: PipelineRequest):
+        cache_valid, token = token_utils.is_entra_token_cache_valid(self._entra_token_cache, request)
+        if cache_valid and token_utils.is_acs_token_cache_valid(self._response_cache):
+            response = self._response_cache
+        else:
+            self._entra_token_cache = token
+            response = self.next.send(request)
+            self._response_cache = response
+        if response is None:
+            raise RuntimeError("Failed to obtain a valid PipelineResponse in EntraTokenGuardPolicy.send")
+        return response

sdk/communication/azure-communication-callautomation/azure/communication/callautomation/_shared/entra_token_guard_policy_async.py

@@ -0,0 +1,30 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+from azure.core.pipeline.policies import AsyncHTTPPolicy
+from azure.core.pipeline import PipelineRequest
+from . import token_utils
+
+
+class EntraTokenGuardPolicy(AsyncHTTPPolicy):
+    """Async pipeline policy that caches the response for a given Entra token and reuses it if valid."""
+
+    def __init__(self):
+        super().__init__()
+        self._entra_token_cache = None
+        self._response_cache = None
+
+    async def send(self, request: PipelineRequest):
+        cache_valid, token = token_utils.is_entra_token_cache_valid(self._entra_token_cache, request)
+        if cache_valid and token_utils.is_acs_token_cache_valid(self._response_cache):
+            response = self._response_cache
+        else:
+            self._entra_token_cache = token
+            response = await self.next.send(request)
+            self._response_cache = response
+        if response is None:
+            raise RuntimeError("Failed to obtain a valid PipelineResponse in AsyncEntraTokenGuardPolicy.send")
+        return response

sdk/communication/azure-communication-callautomation/azure/communication/callautomation/_shared/models.py

@@ -5,7 +5,7 @@
 from enum import Enum
 import warnings
 from typing import Mapping, Optional, Union, Any, cast
-from typing_extensions import Literal, TypedDict, Protocol, runtime_checkable
+from typing_extensions import Literal, TypedDict, Protocol, runtime_checkable, NotRequired
 
 from azure.core import CaseInsensitiveEnumMeta
 
@@ -37,6 +37,7 @@ class CommunicationIdentifierKind(str, Enum, metaclass=DeprecatedEnumMeta):
     PHONE_NUMBER = "phone_number"
     MICROSOFT_TEAMS_USER = "microsoft_teams_user"
     MICROSOFT_TEAMS_APP = "microsoft_teams_app"
+    TEAMS_EXTENSION_USER = "teams_extension_user"
 
 
 class CommunicationCloudEnvironment(str, Enum, metaclass=CaseInsensitiveEnumMeta):
@@ -86,6 +87,8 @@ def properties(self) -> Mapping[str, Any]:
 ACS_USER_GCCH_CLOUD_PREFIX = "8:gcch-acs:"
 SPOOL_USER_PREFIX = "8:spool:"
 
+PHONE_NUMBER_ANONYMOUS_SUFFIX = "anonymous"
+
 
 class CommunicationUserProperties(TypedDict):
     """Dictionary of properties for a CommunicationUserIdentifier."""
@@ -127,6 +130,10 @@ class PhoneNumberProperties(TypedDict):
 
     value: str
     """The phone number in E.164 format."""
+    asserted_id: NotRequired[str]
+    """The asserted Id set on a phone number to distinguish from other connections made through the same number."""
+    is_anonymous: NotRequired[bool]
+    """True if the phone number is anonymous, e.g. when used to represent a hidden caller Id."""
 
 
 class PhoneNumberIdentifier:
@@ -145,8 +152,21 @@ def __init__(self, value: str, **kwargs: Any) -> None:
         :keyword str raw_id: The raw ID of the identifier. If not specified, this will be constructed from
           the 'value' parameter.
         """
-        self.properties = PhoneNumberProperties(value=value)
+
         raw_id: Optional[str] = kwargs.get("raw_id")
+        is_anonymous: bool
+
+        if raw_id is not None:
+            phone_number = raw_id[len(PHONE_NUMBER_PREFIX):]
+            is_anonymous = phone_number == PHONE_NUMBER_ANONYMOUS_SUFFIX
+            asserted_id_index = -1 if is_anonymous else phone_number.rfind("_") + 1
+            has_asserted_id = 0 < asserted_id_index < len(phone_number)
+            props = {"value": value, "is_anonymous": is_anonymous}
+            if has_asserted_id:
+                props["asserted_id"] = phone_number[asserted_id_index:]
+            self.properties = PhoneNumberProperties(**props)  # type: ignore
+        else:
+            self.properties = PhoneNumberProperties(value=value)
         self.raw_id = raw_id if raw_id is not None else self._format_raw_id(self.properties)
 
     def __eq__(self, other):
@@ -163,7 +183,6 @@ def _format_raw_id(self, properties: PhoneNumberProperties) -> str:
         value = properties["value"]
         return f"{PHONE_NUMBER_PREFIX}{value}"
 
-
 class UnknownIdentifier:
     """Represents an identifier of an unknown type.
 
@@ -223,7 +242,7 @@ def __init__(self, user_id: str, **kwargs: Any) -> None:
         :param str user_id: Microsoft Teams user id.
         :keyword bool is_anonymous: `True` if the identifier is anonymous. Default value is `False`.
         :keyword cloud: Cloud environment that the user belongs to. Default value is `PUBLIC`.
-        :paramtype cloud: str or ~azure.communication.chat.CommunicationCloudEnvironment
+        :paramtype cloud: str or ~azure.communication.callautomation.CommunicationCloudEnvironment
         :keyword str raw_id: The raw ID of the identifier. If not specified, this value will be constructed from
          the other properties.
         """
@@ -294,7 +313,7 @@ def __init__(self, app_id: str, **kwargs: Any) -> None:
         """
         :param str app_id: Microsoft Teams application id.
         :keyword cloud: Cloud environment that the application belongs to. Default value is `PUBLIC`.
-        :paramtype cloud: str or ~azure.communication.chat.CommunicationCloudEnvironment
+        :paramtype cloud: str or ~azure.communication.callautomation.CommunicationCloudEnvironment
         :keyword str raw_id: The raw ID of the identifier. If not specified, this value will be constructed
          from the other properties.
         """
@@ -338,7 +357,7 @@ def __init__(self, bot_id, **kwargs):
         :keyword bool is_resource_account_configured: `False` if the identifier is global.
          Default value is `True` for tennantzed bots.
         :keyword cloud: Cloud environment that the bot belongs to. Default value is `PUBLIC`.
-        :paramtype cloud: str or ~azure.communication.chat.CommunicationCloudEnvironment
+        :paramtype cloud: str or ~azure.communication.callautomation.CommunicationCloudEnvironment
         """
         warnings.warn(
             "The MicrosoftBotIdentifier is deprecated and has been replaced by MicrosoftTeamsAppIdentifier.",
@@ -347,6 +366,88 @@ def __init__(self, bot_id, **kwargs):
         super().__init__(bot_id, **kwargs)
 
 
+class TeamsExtensionUserProperties(TypedDict):
+    """Dictionary of properties for a TeamsExtensionUserIdentifier."""
+
+    user_id: str
+    """The id of the Teams extension user."""
+    tenant_id: str
+    """The tenant id associated with the user."""
+    resource_id: str
+    """The Communication Services resource id."""
+    cloud: Union[CommunicationCloudEnvironment, str]
+    """Cloud environment that this identifier belongs to."""
+
+
+class TeamsExtensionUserIdentifier:
+    """Represents an identifier for a Teams Extension user."""
+
+    kind: Literal[CommunicationIdentifierKind.TEAMS_EXTENSION_USER] = CommunicationIdentifierKind.TEAMS_EXTENSION_USER
+    """The type of identifier."""
+    properties: TeamsExtensionUserProperties
+    """The properties of the identifier."""
+    raw_id: str
+    """The raw ID of the identifier."""
+
+    def __init__(
+        self,
+        user_id: str,
+        tenant_id: str,
+        resource_id: str,
+        **kwargs: Any
+    ) -> None:
+        """
+        :param str user_id: Teams extension user id.
+        :param str tenant_id: Tenant id associated with the user.
+        :param str resource_id: The Communication Services resource id.
+        :keyword cloud: Cloud environment that the user belongs to. Default value is `PUBLIC`.
+        :paramtype cloud: str or ~azure.communication.callautomation.CommunicationCloudEnvironment
+        :keyword str raw_id: The raw ID of the identifier.
+         If not specified, this value will be constructed from the other properties.
+        """
+        self.properties = TeamsExtensionUserProperties(
+            user_id=user_id,
+            tenant_id=tenant_id,
+            resource_id=resource_id,
+            cloud=kwargs.get("cloud") or CommunicationCloudEnvironment.PUBLIC,
+        )
+        raw_id: Optional[str] = kwargs.get("raw_id")
+        self.raw_id = raw_id if raw_id is not None else self._format_raw_id(self.properties)
+
+    def __eq__(self, other):
+        try:
+            if other.raw_id:
+                return self.raw_id == other.raw_id
+            return self.raw_id == self._format_raw_id(other.properties)
+        except Exception:  # pylint: disable=broad-except
+            return False
+
+    def _format_raw_id(self, properties: TeamsExtensionUserProperties) -> str:
+        # The prefix depends on the cloud
+        cloud = properties["cloud"]
+        if cloud == CommunicationCloudEnvironment.DOD:
+            prefix = ACS_USER_DOD_CLOUD_PREFIX
+        elif cloud == CommunicationCloudEnvironment.GCCH:
+            prefix = ACS_USER_GCCH_CLOUD_PREFIX
+        else:
+            prefix = ACS_USER_PREFIX
+        return f"{prefix}{properties['resource_id']}_{properties['tenant_id']}_{properties['user_id']}"
+
+def try_create_teams_extension_user(prefix: str, suffix: str) -> Optional[TeamsExtensionUserIdentifier]:
+    segments = suffix.split("_")
+    if len(segments) != 3:
+        return None
+    resource_id, tenant_id, user_id = segments
+    if prefix == ACS_USER_PREFIX:
+        cloud = CommunicationCloudEnvironment.PUBLIC
+    elif prefix == ACS_USER_DOD_CLOUD_PREFIX:
+        cloud = CommunicationCloudEnvironment.DOD
+    elif prefix == ACS_USER_GCCH_CLOUD_PREFIX:
+        cloud = CommunicationCloudEnvironment.GCCH
+    else:
+        raise ValueError("Invalid MRI")
+    return TeamsExtensionUserIdentifier(user_id, tenant_id, resource_id, cloud=cloud)
+
 def identifier_from_raw_id(raw_id: str) -> CommunicationIdentifier:  # pylint: disable=too-many-return-statements
     """
     Creates a CommunicationIdentifier from a given raw ID.
@@ -407,11 +508,16 @@ def identifier_from_raw_id(raw_id: str) -> CommunicationIdentifier:  # pylint: d
             cloud=CommunicationCloudEnvironment.GCCH,
             raw_id=raw_id,
         )
+    if prefix == SPOOL_USER_PREFIX:
+        return CommunicationUserIdentifier(id=raw_id, raw_id=raw_id)
+
     if prefix in [
         ACS_USER_PREFIX,
         ACS_USER_DOD_CLOUD_PREFIX,
         ACS_USER_GCCH_CLOUD_PREFIX,
-        SPOOL_USER_PREFIX,
     ]:
+        identifier = try_create_teams_extension_user(prefix, suffix)
+        if identifier is not None:
+            return identifier
         return CommunicationUserIdentifier(id=raw_id, raw_id=raw_id)
     return UnknownIdentifier(identifier=raw_id)

sdk/communication/azure-communication-callautomation/azure/communication/callautomation/_shared/token_exchange.py

@@ -0,0 +1,78 @@
+# -------------------------------------------------------------------------
+# Copyright (c) Microsoft Corporation. All rights reserved.
+# Licensed under the MIT License. See License.txt in the project root for
+# license information.
+# --------------------------------------------------------------------------
+
+import json
+from typing import Any, List, Optional
+# pylint: disable=non-abstract-transport-import
+# pylint: disable=no-name-in-module
+from azure.core.pipeline.transport import RequestsTransport
+from azure.core.credentials import AccessToken
+from azure.core.pipeline import Pipeline, PipelineResponse
+from azure.core.pipeline.policies import BearerTokenCredentialPolicy
+from azure.core.exceptions import HttpResponseError
+from azure.core.credentials import TokenCredential
+from azure.core.pipeline.policies import RetryPolicy
+from .entra_token_guard_policy import EntraTokenGuardPolicy
+from . import token_utils
+
+
+class TokenExchangeClient:
+    """Represents a client that exchanges an Entra token for an Azure Communication Services (ACS) token.
+    
+    :param resource_endpoint: The endpoint URL of the resource to authenticate against.
+    :param credential: The credential to use for token exchange.
+    :param scopes: The scopes to request during the token exchange.
+    :keyword transport: Optional transport to use for the pipeline.
+    """
+
+    # pylint: disable=C4748
+    # pylint: disable=client-method-missing-type-annotations
+    def __init__(
+            self,
+            resource_endpoint: str,
+            credential: TokenCredential,
+            scopes: Optional[List[str]] = None,
+            **kwargs: Any):
+
+        self._resource_endpoint = resource_endpoint
+        self._scopes = scopes or ["https://communication.azure.com/clients/.default"]
+        self._credential = credential
+        pipeline_transport = kwargs.get("transport", None)
+        self._pipeline = self._create_pipeline_from_options(pipeline_transport)
+
+    def _create_pipeline_from_options(self, pipeline_transport):
+        auth_policy = BearerTokenCredentialPolicy(self._credential, *self._scopes)
+        entra_token_guard_policy = EntraTokenGuardPolicy()
+        retry_policy = RetryPolicy()
+        policies = [auth_policy, entra_token_guard_policy, retry_policy]
+        if pipeline_transport:
+            return Pipeline(policies=policies, transport=pipeline_transport)
+        return Pipeline(policies=policies, transport=RequestsTransport())
+
+    def exchange_entra_token(self) -> AccessToken:
+        message = token_utils.create_request_message(self._resource_endpoint, self._scopes)
+        response = self._pipeline.run(message)
+        return self._parse_access_token_from_response(response)
+
+    def _parse_access_token_from_response(self, response: PipelineResponse) -> AccessToken:
+        if response.http_response.status_code == 200:
+            try:
+                content = response.http_response.text()
+                data = json.loads(content)
+                access_token_json = data["accessToken"]
+                token = access_token_json["token"]
+                expires_on = access_token_json["expiresOn"]
+                expires_on_epoch = token_utils.parse_expires_on(expires_on, response)
+                if expires_on_epoch is None:
+                    raise ValueError("Failed to parse 'expiresOn' value from access token response")
+                return AccessToken(token, expires_on_epoch)
+            except Exception as ex:
+                raise ValueError("Failed to parse access token from response") from ex
+        else:
+            raise HttpResponseError(
+                message="Failed to exchange Entra token for ACS token",
+                response=response.http_response
+            )