[OPS Common SDK] Updating Communication Common SDK to version supporting Teams Phone Extensibility GA version (Azure#50140)

paveldostalms · web-flow · commit 36015f9d821d · 2025-05-30T09:43:29.000+02:00
* Update API version
Update API version for TeamsExtension API called from CommonSDK

* Ensure that null/empty scopes are handled when setting, Validate Scopes in options
Never allow empty Scopes in EntraCommunicationTokenCredentialOptions
 
* New version changelog and readme
diff --git a/sdk/communication/Azure.Communication.Common/CHANGELOG.md b/sdk/communication/Azure.Communication.Common/CHANGELOG.md
@@ -1,14 +1,11 @@
 # Release History
 
-## 1.4.0-beta.2 (Unreleased)
+## 1.4.0 (Unreleased)
 
 ### Features Added
-
-### Breaking Changes
-
-### Bugs Fixed
-
-### Other Changes
+- Introduced support for `Azure.Core.TokenCredential` with `EntraCommunicationTokenCredentialOptions`, allowing an Entra user with a Teams license to use Teams Phone Extensibility features through the Azure Communication Services resource.
+- Added support for a new communication identifier `TeamsExtensionUserIdentifier` which maps rawIds with format `8:acs:{resourceId}_{tenantId}_{userId}`.
+- Added `IsAnonymous` and `AssertedId` properties to `PhoneNumberIdentifier`.
 
 ## 1.4.0-beta.1 (2025-04-01)
 
diff --git a/sdk/communication/Azure.Communication.Common/README.md b/sdk/communication/Azure.Communication.Common/README.md
@@ -106,7 +106,9 @@ using var tokenCredential = new CommunicationTokenCredential(
 
 For scenarios where an Entra user can be used with Communication Services, you need to initialize any implementation of [Azure.Core.TokenCredential](https://docs.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet) and provide it to the ``EntraCommunicationTokenCredentialOptions``.
 Along with this, you must provide the URI of the Azure Communication Services resource and the scopes required for the Entra user token. These scopes determine the permissions granted to the token.
-If the scopes are not provided, by default, it sets the scopes to `https://communication.azure.com/clients/.default`.
+
+This approach needs to be used for authorizing an Entra user with a Teams license to use Teams Phone Extensibility features through your Azure Communication Services resource.
+This requires providing the `https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls` scope.
 ```C# 
 var options = new InteractiveBrowserCredentialOptions
     {
@@ -119,16 +121,18 @@ var entraTokenCredential = new InteractiveBrowserCredential(options);
 var entraTokenCredentialOptions = new EntraCommunicationTokenCredentialOptions(
     resourceEndpoint: "https://<your-resource>.communication.azure.com",
     entraTokenCredential: entraTokenCredential)
+    )
     {
-      Scopes = new[] { "https://communication.azure.com/clients/VoIP" }
+      Scopes = new[] { "https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls" }
     };
 
 var credential = new CommunicationTokenCredential(entraTokenCredentialOptions);
 
 ```
 
-The same approach can be used for authorizing an Entra user with a Teams license to use Teams Phone Extensibility features through your Azure Communication Services resource.
-This requires providing the `https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls` scope
+Other scenarios for Entra users to utilize Azure Communication Services are currently in the **preview stage only and should not be used in production**.
+The scopes for these scenarios follow the format `https://communication.azure.com/clients/<Azure Communication Services Clients API permission>`.
+If specific scopes are not provided, the default scopes will be set to `https://communication.azure.com/clients/.default`.
 ```C# 
 var options = new InteractiveBrowserCredentialOptions
     {
@@ -141,9 +145,8 @@ var entraTokenCredential = new InteractiveBrowserCredential(options);
 var entraTokenCredentialOptions = new EntraCommunicationTokenCredentialOptions(
     resourceEndpoint: "https://<your-resource>.communication.azure.com",
     entraTokenCredential: entraTokenCredential)
-    )
     {
-      Scopes = new[] { "https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls" }
+      Scopes = new[] { "https://communication.azure.com/clients/VoIP" }
     };
 
 var credential = new CommunicationTokenCredential(entraTokenCredentialOptions);
diff --git a/sdk/communication/Azure.Communication.Common/src/Azure.Communication.Common.csproj b/sdk/communication/Azure.Communication.Common/src/Azure.Communication.Common.csproj
@@ -5,7 +5,7 @@
       For this release, see notes - https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Common/README.md and https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/communication/Azure.Communication.Common/CHANGELOG.md.
     </Description>
     <AssemblyTitle>Azure Communication Services Common</AssemblyTitle>
-    <Version>1.4.0-beta.2</Version>
+    <Version>1.4.0</Version>
     <!--The ApiCompatVersion is managed automatically and should not generally be modified manually.-->
     <ApiCompatVersion>1.3.0</ApiCompatVersion>
     <PackageTags>Microsoft Azure Communication Service;Microsoft;Azure;Azure Communication Service;Communication;$(PackageCommonTags)</PackageTags>
diff --git a/sdk/communication/Azure.Communication.Common/src/EntraCommunicationTokenCredentialOptions.cs b/sdk/communication/Azure.Communication.Common/src/EntraCommunicationTokenCredentialOptions.cs
@@ -2,6 +2,7 @@
 // Licensed under the MIT License.
 
 using System;
+using System.Linq;
 using Azure.Core;
 
 namespace Azure.Communication
@@ -11,7 +12,9 @@ namespace Azure.Communication
     /// </summary>
     public class EntraCommunicationTokenCredentialOptions
     {
-        private static string[] DefaultScopes = { "https://communication.azure.com/clients/.default" };
+        private static string[] DefaultScopes = { EntraCommunicationTokenScopes.DefaultScopes };
+        private string[] _scopes;
+
         /// <summary>
         /// The URI of the Azure Communication Services resource.
         /// </summary>
@@ -25,7 +28,13 @@ public class EntraCommunicationTokenCredentialOptions
         /// <summary>
         /// The scopes required for the Entra user token. These scopes determine the permissions granted to the token. For example, ["https://communication.azure.com/clients/VoIP"].
         /// </summary>
-        public string[] Scopes { get; set; }
+        public string[] Scopes {
+            get => _scopes;
+            set
+            {
+                _scopes = ValidateScopes(value);
+            }
+        }
 
         /// <summary>
         /// Initializes a new instance of <see cref="EntraCommunicationTokenCredentialOptions"/>.
@@ -43,5 +52,22 @@ public EntraCommunicationTokenCredentialOptions(
             this.TokenCredential = entraTokenCredential;
             this.Scopes = DefaultScopes;
         }
+
+        private static string[] ValidateScopes(string[] scopes)
+        {
+            if (scopes == null || scopes.Length == 0)
+            {
+                throw new ArgumentException(
+                    $"Scopes must not be null or empty. Ensure all scopes start with either {EntraCommunicationTokenScopes.TeamsExtensionScopePrefix} or {EntraCommunicationTokenScopes.CommunicationClientsScopePrefix}.", nameof(scopes));
+            }
+
+            if (scopes.All(item => item.StartsWith(EntraCommunicationTokenScopes.TeamsExtensionScopePrefix))
+                || scopes.All(item => item.StartsWith(EntraCommunicationTokenScopes.CommunicationClientsScopePrefix)))
+            {
+                return scopes;
+            }
+
+            throw new ArgumentException($"Scopes validation failed. Ensure all scopes start with either {EntraCommunicationTokenScopes.TeamsExtensionScopePrefix} or {EntraCommunicationTokenScopes.CommunicationClientsScopePrefix}.", nameof(_scopes));
+        }
     }
 }
diff --git a/sdk/communication/Azure.Communication.Common/src/EntraCommunicationTokenScopes.cs b/sdk/communication/Azure.Communication.Common/src/EntraCommunicationTokenScopes.cs
@@ -0,0 +1,15 @@
+﻿// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace Azure.Communication
+{
+    /// <summary>
+    /// The Entra Communication Token Options.
+    /// </summary>
+    internal static class EntraCommunicationTokenScopes
+    {
+        public const string TeamsExtensionScopePrefix = "https://auth.msft.communication.azure.com/";
+        public const string CommunicationClientsScopePrefix = "https://communication.azure.com/clients/";
+        public const string DefaultScopes = CommunicationClientsScopePrefix + ".default";
+    }
+}
diff --git a/sdk/communication/Azure.Communication.Common/src/EntraTokenCredential.cs b/sdk/communication/Azure.Communication.Common/src/EntraTokenCredential.cs
@@ -17,10 +17,8 @@ namespace Azure.Communication
     /// </summary>
     internal sealed class EntraTokenCredential : ICommunicationTokenCredential
     {
-        private const string TeamsExtensionScopePrefix = "https://auth.msft.communication.azure.com/";
-        private const string CommunicationClientsScopePrefix = "https://communication.azure.com/clients/";
         private const string TeamsExtensionEndpoint = "/access/teamsExtension/:exchangeAccessToken";
-        private const string TeamsExtensionApiVersion = "2025-03-02-preview";
+        private const string TeamsExtensionApiVersion = "2025-06-30";
         private const string CommunicationClientsEndpoint = "/access/entra/:exchangeAccessToken";
         private const string CommunicationClientsApiVersion = "2025-03-02-preview";
 
@@ -36,6 +34,10 @@ internal sealed class EntraTokenCredential : ICommunicationTokenCredential
         /// <param name="pipelineTransport">Only for testing.</param>
         public EntraTokenCredential(EntraCommunicationTokenCredentialOptions options, HttpPipelineTransport pipelineTransport = null)
         {
+            Argument.AssertNotNull(options, nameof(options));
+            // Should not ever happen, validated in EntraCommunicationTokenCredentialOptions
+            Argument.AssertNotNullOrEmpty(options.Scopes, nameof(options.Scopes));
+
             this._resourceEndpoint = options.ResourceEndpoint;
             this._scopes = (ICollection<string>)options.Scopes.Clone();
             _pipeline = CreatePipelineFromOptions(options, pipelineTransport);
@@ -134,21 +136,17 @@ private RequestUriBuilder CreateRequestUri()
 
         private (string Endpoint, string ApiVersion) DetermineEndpointAndApiVersion()
         {
-            if (_scopes == null || !_scopes.Any())
-            {
-                throw new ArgumentException($"Scopes validation failed. Ensure all scopes start with either {TeamsExtensionScopePrefix} or {CommunicationClientsScopePrefix}.", nameof(_scopes));
-            }
-            else if (_scopes.All(item => item.StartsWith(TeamsExtensionScopePrefix)))
+            if (_scopes.All(item => item.StartsWith(EntraCommunicationTokenScopes.TeamsExtensionScopePrefix)))
             {
                 return (TeamsExtensionEndpoint, TeamsExtensionApiVersion);
             }
-            else if (_scopes.All(item => item.StartsWith(CommunicationClientsScopePrefix)))
+            else if (_scopes.All(item => item.StartsWith(EntraCommunicationTokenScopes.CommunicationClientsScopePrefix)))
             {
                 return (CommunicationClientsEndpoint, CommunicationClientsApiVersion);
             }
             else
             {
-                throw new ArgumentException($"Scopes validation failed. Ensure all scopes start with either {TeamsExtensionScopePrefix} or {CommunicationClientsScopePrefix}.", nameof(_scopes));
+                throw new ArgumentException($"Scopes validation failed. Ensure all scopes start with either {EntraCommunicationTokenScopes.TeamsExtensionScopePrefix} or {EntraCommunicationTokenScopes.CommunicationClientsScopePrefix}.", nameof(_scopes));
             }
         }
 
diff --git a/sdk/communication/Azure.Communication.Common/tests/Identity/EntraTokenCredentialTest.cs b/sdk/communication/Azure.Communication.Common/tests/Identity/EntraTokenCredentialTest.cs
@@ -43,7 +43,6 @@ public class EntraTokenCredentialTest
             new object[] { new string[] { teamsExtensionScope, communicationClientsScope } },
             new object[] { new string[] { "invalidScope" } },
             new object[] { new string[] { "" } },
-            new object[] { new string[] { } }
         };
 
         [SetUp]
@@ -57,7 +56,7 @@ public void Setup()
         }
 
         [Test, TestCaseSource(nameof(validScopes))]
-        public void EntraTokenCredential_Init_ThrowsErrorWithNulls(string[] scopes)
+        public void EntraCommunicationTokenCredentialOptions_Init_ThrowsErrorWithNulls(string[] scopes)
         {
             Assert.Throws<ArgumentNullException>(() => new EntraCommunicationTokenCredentialOptions(
                 null,
@@ -82,7 +81,35 @@ public void EntraTokenCredential_Init_ThrowsErrorWithNulls(string[] scopes)
         }
 
         [Test]
-        public void EntraTokenCredential_InitWithoutScopes_InitsWithDefaultScope()
+        public void EntraCommunicationTokenCredentialOptions_NullOrEmptyScopes_ThrowsError()
+        {
+            Assert.Throws<ArgumentException>(() => new EntraCommunicationTokenCredentialOptions(
+                _resourceEndpoint,
+                _mockTokenCredential.Object)
+            {
+                Scopes = null
+            });
+            Assert.Throws<ArgumentException>(() => new EntraCommunicationTokenCredentialOptions(
+                _resourceEndpoint,
+                _mockTokenCredential.Object)
+            {
+                Scopes = Array.Empty<string>()
+            });
+        }
+
+        [Test, TestCaseSource(nameof(invalidScopes))]
+        public void EntraCommunicationTokenCredentialOptions_InvalidScopes_ThrowsForInvalidScopes(string[] scopes)
+        {
+            Assert.Throws<ArgumentException>(() => new EntraCommunicationTokenCredentialOptions(
+                _resourceEndpoint,
+                _mockTokenCredential.Object)
+            {
+                Scopes = scopes
+            });
+        }
+
+        [Test]
+        public void EntraCommunicationTokenCredentialOptions_InitWithoutScopes_InitsWithDefaultScope()
         {
             var credential = new EntraCommunicationTokenCredentialOptions(
                 _resourceEndpoint,
@@ -91,6 +118,15 @@ public void EntraTokenCredential_InitWithoutScopes_InitsWithDefaultScope()
             Assert.AreEqual(credential.Scopes, scopes);
         }
 
+        [Test]
+        public void EntraTokenCredential_Ctor_NullOptionsThrows()
+        {
+            // Arrange
+            var mockTransport = CreateMockTransport(new[] { CreateMockResponse(200, TokenResponse) });
+            // Assert
+            Assert.Throws<ArgumentNullException>(() => new EntraTokenCredential(null, mockTransport));
+        }
+
         [Test, TestCaseSource(nameof(validScopes))]
         public void EntraTokenCredential_Init_FetchesTokenImmediately(string[] scopes)
         {
@@ -261,7 +297,12 @@ public void EntraTokenCredential_GetToken_RetriesThreeTimesOnTransientError(stri
         public void EntraTokenCredential_GetToken_ThrowsForInvalidScopes(string[] scopes)
         {
             // Arrange
-            var options = CreateEntraTokenCredentialOptions(scopes);
+            var options = new EntraCommunicationTokenCredentialOptions(_resourceEndpoint, _mockTokenCredential.Object)
+            {
+                Scopes = Enumerable.Repeat(communicationClientsScope, scopes.Length).ToArray()
+            };
+            scopes.CopyTo(options.Scopes, 0);
+
             var mockResponses = new MockResponse[]
             {
                 CreateMockResponse(200, TokenResponse)

Original file line number	Diff line number	Diff line change
`@@ -17,10 +17,8 @@ namespace Azure.Communication`
`17`	`17`	`/// </summary>`
`18`	`18`	`internal sealed class EntraTokenCredential : ICommunicationTokenCredential`
`19`	`19`	`{`
`20`		`- private const string TeamsExtensionScopePrefix = "https://auth.msft.communication.azure.com/";`
`21`		`- private const string CommunicationClientsScopePrefix = "https://communication.azure.com/clients/";`
`22`	`20`	`private const string TeamsExtensionEndpoint = "/access/teamsExtension/:exchangeAccessToken";`
`23`		`- private const string TeamsExtensionApiVersion = "2025-03-02-preview";`
	`21`	`+ private const string TeamsExtensionApiVersion = "2025-06-30";`
`24`	`22`	`private const string CommunicationClientsEndpoint = "/access/entra/:exchangeAccessToken";`
`25`	`23`	`private const string CommunicationClientsApiVersion = "2025-03-02-preview";`
`26`	`24`
`@@ -36,6 +34,10 @@ internal sealed class EntraTokenCredential : ICommunicationTokenCredential`
`36`	`34`	`/// <param name="pipelineTransport">Only for testing.</param>`
`37`	`35`	`public EntraTokenCredential(EntraCommunicationTokenCredentialOptions options, HttpPipelineTransport pipelineTransport = null)`
`38`	`36`	`{`
	`37`	`+ Argument.AssertNotNull(options, nameof(options));`
	`38`	`+ // Should not ever happen, validated in EntraCommunicationTokenCredentialOptions`
	`39`	`+ Argument.AssertNotNullOrEmpty(options.Scopes, nameof(options.Scopes));`
	`40`	`+`
`39`	`41`	`this._resourceEndpoint = options.ResourceEndpoint;`
`40`	`42`	`this._scopes = (ICollection<string>)options.Scopes.Clone();`
`41`	`43`	`_pipeline = CreatePipelineFromOptions(options, pipelineTransport);`
`@@ -134,21 +136,17 @@ private RequestUriBuilder CreateRequestUri()`
`134`	`136`
`135`	`137`	`private (string Endpoint, string ApiVersion) DetermineEndpointAndApiVersion()`
`136`	`138`	`{`
`137`		`- if (_scopes == null \|\| !_scopes.Any())`
`138`		`- {`
`139`		`- throw new ArgumentException($"Scopes validation failed. Ensure all scopes start with either {TeamsExtensionScopePrefix} or {CommunicationClientsScopePrefix}.", nameof(_scopes));`
`140`		`- }`
`141`		`- else if (_scopes.All(item => item.StartsWith(TeamsExtensionScopePrefix)))`
	`139`	`+ if (_scopes.All(item => item.StartsWith(EntraCommunicationTokenScopes.TeamsExtensionScopePrefix)))`
`142`	`140`	`{`
`143`	`141`	`return (TeamsExtensionEndpoint, TeamsExtensionApiVersion);`
`144`	`142`	`}`
`145`		`- else if (_scopes.All(item => item.StartsWith(CommunicationClientsScopePrefix)))`
	`143`	`+ else if (_scopes.All(item => item.StartsWith(EntraCommunicationTokenScopes.CommunicationClientsScopePrefix)))`
`146`	`144`	`{`
`147`	`145`	`return (CommunicationClientsEndpoint, CommunicationClientsApiVersion);`
`148`	`146`	`}`
`149`	`147`	`else`
`150`	`148`	`{`
`151`		`- throw new ArgumentException($"Scopes validation failed. Ensure all scopes start with either {TeamsExtensionScopePrefix} or {CommunicationClientsScopePrefix}.", nameof(_scopes));`
	`149`	`+ throw new ArgumentException($"Scopes validation failed. Ensure all scopes start with either {EntraCommunicationTokenScopes.TeamsExtensionScopePrefix} or {EntraCommunicationTokenScopes.CommunicationClientsScopePrefix}.", nameof(_scopes));`
`152`	`150`	`}`
`153`	`151`	`}`
`154`	`152`