[ACS][Common] OPS - Dual Persona

eng/Packages.Data.props

@@ -98,7 +98,7 @@
     <PackageReference Update="System.Security.Cryptography.Cose" Version="7.0.0" />
     <PackageReference Update="System.Threading.Channels" Version="6.0.0" />
     <PackageReference Update="System.Threading.Tasks.Extensions" Version="4.5.4" />
-    <PackageReference Update="System.Text.Json" Version="6.0.9" />
+    <PackageReference Update="System.Text.Json" Version="6.0.10" />
     <PackageReference Update="System.Text.Encodings.Web" Version="6.0.0" />
     <PackageReference Update="System.ValueTuple" Version="4.5.0" />
     <PackageReference Update="Microsoft.Bcl.AsyncInterfaces" Version="6.0.0" />

sdk/communication/Azure.Communication.Common/README.md

@@ -38,6 +38,7 @@ Depending on your scenario, you may want to initialize the `CommunicationTokenCr
 
 - a static token (suitable for short-lived clients used to e.g. send one-off Chat messages) or
 - a callback function that ensures a continuous authentication state (ideal e.g. for long Calling sessions).
+- a token credential capable of obtaining an Entra user token. You can provide any implementation of [Azure.Core.TokenCredential](https://docs.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet). It is suitable for scenarios where Entra user access tokens are needed to authenticate with Communication Services.
 
 The tokens supplied to the `CommunicationTokenCredential` either through the constructor or via the token refresher callback can be obtained using the Azure Communication Identity library.
 
@@ -101,6 +102,31 @@ using var tokenCredential = new CommunicationTokenCredential(
     });
 ```
 
+### Create a credential with a token credential capable of obtaining an Entra user token
+
+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:
+
+```C# 
+var options = new InteractiveBrowserCredentialOptions
+    {
+        TenantId = "<your-tenant-id>",
+        ClientId = "<your-client-id>",
+        RedirectUri = new Uri("<your-redirect-uri>"),
+        AuthorityHost = new Uri("https://login.microsoftonline.com/<your-tenant-id>")
+    };
+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" }
+);
+
+var credential = new CommunicationTokenCredential(entraTokenCredentialOptions);
+
+```
+
 ## Troubleshooting
 The proactive refreshing failures happen in a background thread and to avoid crashing your app the exceptions will be silently handled.
 All the other failures will happen during your request using other clients such as chat where you can catch the exception using `RequestFailedException`.

sdk/communication/Azure.Communication.Common/api/Azure.Communication.Common.netstandard2.0.cs

@@ -34,6 +34,7 @@ protected CommunicationIdentifier() { }
     public sealed partial class CommunicationTokenCredential : System.IDisposable
     {
         public CommunicationTokenCredential(Azure.Communication.CommunicationTokenRefreshOptions options) { }
+        public CommunicationTokenCredential(Azure.Communication.EntraCommunicationTokenCredentialOptions options) { }
         public CommunicationTokenCredential(string token) { }
         public void Dispose() { }
         public Azure.Core.AccessToken GetToken(System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
@@ -53,6 +54,14 @@ public CommunicationUserIdentifier(string id) { }
         public override bool Equals(Azure.Communication.CommunicationIdentifier other) { throw null; }
         public override string ToString() { throw null; }
     }
+    public partial class EntraCommunicationTokenCredentialOptions
+    {
+        public EntraCommunicationTokenCredentialOptions(string resourceEndpoint, Azure.Core.TokenCredential entraTokenCredential) { }
+        public EntraCommunicationTokenCredentialOptions(string resourceEndpoint, Azure.Core.TokenCredential entraTokenCredential, string[] scopes) { }
+        public string ResourceEndpoint { get { throw null; } }
+        public string[] Scopes { get { throw null; } }
+        public Azure.Core.TokenCredential TokenCredential { get { throw null; } }
+    }
     public partial class MicrosoftTeamsAppIdentifier : Azure.Communication.CommunicationIdentifier
     {
         public MicrosoftTeamsAppIdentifier(string appId, Azure.Communication.CommunicationCloudEnvironment? cloud = default(Azure.Communication.CommunicationCloudEnvironment?)) { }

sdk/communication/Azure.Communication.Common/src/CommunicationTokenCredential.cs

@@ -34,6 +34,16 @@ public CommunicationTokenCredential(CommunicationTokenRefreshOptions options)
             _tokenCredential = new AutoRefreshTokenCredential(options);
         }
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="CommunicationTokenCredential"/>.
+        /// </summary>
+        /// <param name="options">The options for how the token will be fetched</param>
+        public CommunicationTokenCredential(EntraCommunicationTokenCredentialOptions options)
+        {
+            Argument.AssertNotNull(options, nameof(options));
+            _tokenCredential = new EntraTokenCredential(options);
+        }
+
         /// <summary>
         /// Gets an <see cref="AccessToken"/> for the user.
         /// </summary>

sdk/communication/Azure.Communication.Common/src/EntraCommunicationTokenCredentialOptions.cs

@@ -0,0 +1,64 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using Azure.Core;
+
+namespace Azure.Communication
+{
+    /// <summary>
+    /// The Entra Communication Token Options.
+    /// </summary>
+    public class EntraCommunicationTokenCredentialOptions
+    {
+        private static string[] DefaultScopes = { "https://communication.azure.com/clients/.default" };
+        /// <summary>
+        /// The URI of the Azure Communication Services resource.
+        /// </summary>
+        public string ResourceEndpoint { get; }
+
+        /// <summary>
+        /// The credential capable of fetching an Entra user token. You can provide any implementation of <see cref="Azure.Core.TokenCredential"/>.
+        /// </summary>
+        public TokenCredential TokenCredential { get; }
+
+        /// <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; }
+
+        /// <summary>
+        /// Initializes a new instance of <see cref="EntraCommunicationTokenCredentialOptions"/>.
+        /// </summary>
+        /// <param name="resourceEndpoint">The URI of the Azure Communication Services resource.For example, https://myResource.communication.azure.com.</param>
+        /// <param name="entraTokenCredential">The credential capable of fetching an Entra user token.</param>
+        /// <param name="scopes">The scopes required for the Entra user token.</param>
+        public EntraCommunicationTokenCredentialOptions(
+            string resourceEndpoint,
+            TokenCredential entraTokenCredential,
+            string[] scopes)
+        {
+            Argument.AssertNotNullOrEmpty(resourceEndpoint, nameof(resourceEndpoint));
+            Argument.AssertNotNull(entraTokenCredential, nameof(entraTokenCredential));
+            Argument.AssertNotNullOrEmpty(scopes, nameof(scopes));
+
+            this.ResourceEndpoint = resourceEndpoint;
+            this.TokenCredential = entraTokenCredential;
+            this.Scopes = scopes;
+        }
+
+        /// <summary>
+        /// Initializes a new instance of <see cref="EntraCommunicationTokenCredentialOptions"/>.
+        /// </summary>
+        /// <param name="resourceEndpoint">The URI of the Azure Communication Services resource.For example, https://myResource.communication.azure.com.</param>
+        /// <param name="entraTokenCredential">The credential capable of fetching an Entra user token.</param>
+        public EntraCommunicationTokenCredentialOptions(
+            string resourceEndpoint,
+            TokenCredential entraTokenCredential) : this(
+                resourceEndpoint,
+                entraTokenCredential,
+                DefaultScopes)
+        {
+        }
+    }
+}

sdk/communication/Azure.Communication.Common/src/EntraTokenCredential.cs

@@ -0,0 +1,145 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Azure.Core;
+using Azure.Core.Pipeline;
+
+namespace Azure.Communication
+{
+    /// <summary>
+    /// Represents a credential that exchanges an Entra token for an Azure Communication Services (ACS) token, enabling access to ACS resources.
+    /// </summary>
+    internal sealed class EntraTokenCredential : ICommunicationTokenCredential
+    {
+        private HttpPipeline _pipeline;
+        private string _resourceEndpoint;
+        private readonly ThreadSafeRefreshableAccessTokenCache _accessTokenCache;
+
+        /// <summary>
+        /// Initializes a new instance of <see cref="EntraTokenCredential"/>.
+        /// </summary>
+        /// <param name="options">The options for how the token will be fetched</param>
+        /// <param name="pipelineTransport">Only for testing.</param>
+        public EntraTokenCredential(EntraCommunicationTokenCredentialOptions options, HttpPipelineTransport pipelineTransport = null)
+        {
+            this._resourceEndpoint = options.ResourceEndpoint;
+            _pipeline = CreatePipelineFromOptions(options, pipelineTransport);
+            _accessTokenCache = new ThreadSafeRefreshableAccessTokenCache(
+                    ExchangeEntraToken,
+                    ExchangeEntraTokenAsync,
+                    false, null, null);
+            _accessTokenCache.GetValueAsync(default);
+        }
+
+        private HttpPipeline CreatePipelineFromOptions(EntraCommunicationTokenCredentialOptions options, HttpPipelineTransport pipelineTransport)
+        {
+            var authenticationPolicy = new BearerTokenAuthenticationPolicy(options.TokenCredential, options.Scopes);
+            var entraTokenGuardPolicy = new EntraTokenGuardPolicy();
+            var clientOptions = ClientOptions.Default;
+            if (pipelineTransport != null)
+            {
+                clientOptions.Transport = pipelineTransport;
+            }
+            return HttpPipelineBuilder.Build(clientOptions, authenticationPolicy, entraTokenGuardPolicy);
+        }
+
+        /// <inheritdoc />
+        public void Dispose()
+        {
+            _pipeline = default;
+            _accessTokenCache.Dispose();
+        }
+
+        /// <summary>
+        /// Gets an <see cref="AccessToken"/>.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token for the task.</param>
+        /// <returns> Contains the access token.</returns>
+        public AccessToken GetToken(CancellationToken cancellationToken = default)
+            => _accessTokenCache.GetValue(cancellationToken, () => true);
+
+        /// <summary>
+        /// Gets an <see cref="AccessToken"/>.
+        /// </summary>
+        /// <param name="cancellationToken">The cancellation token for the task.</param>
+        /// <returns>
+        /// A task that represents the asynchronous get token operation. The value of its <see cref="ValueTask{AccessToken}.Result"/> property contains the access token.
+        /// </returns>
+        public ValueTask<AccessToken> GetTokenAsync(CancellationToken cancellationToken = default)
+            => _accessTokenCache.GetValueAsync(cancellationToken, () => true);
+
+        private AccessToken ExchangeEntraToken(CancellationToken cancellationToken)
+        {
+            return ExchangeEntraTokenAsync(false, cancellationToken).EnsureCompleted();
+        }
+
+        private async ValueTask<AccessToken> ExchangeEntraTokenAsync(CancellationToken cancellationToken)
+        {
+            var result = await ExchangeEntraTokenAsync(true, cancellationToken).ConfigureAwait(false);
+            return result;
+        }
+
+        private async ValueTask<AccessToken> ExchangeEntraTokenAsync(bool async, CancellationToken cancellationToken)
+        {
+            var message = CreateRequestMessage();
+            if (async)
+            {
+                await _pipeline.SendAsync(message, cancellationToken).ConfigureAwait(false);
+            }
+            else
+            {
+                _pipeline.Send(message, cancellationToken);
+            }
+            return ParseAccessTokenFromResponse(message.Response);
+        }
+
+        private HttpMessage CreateRequestMessage()
+        {
+            var uri = new RequestUriBuilder();
+            uri.Reset(new Uri(_resourceEndpoint));
+            uri.AppendPath("/access/entra/:exchangeAccessToken", false);
+            uri.AppendQuery("api-version", "2024-04-01-preview", true);
+
+            var message = _pipeline.CreateMessage();
+            var request = message.Request;
+            request.Uri = uri;
+            request.Method = RequestMethod.Post;
+            request.Headers.Add("Accept", "application/json");
+            request.Headers.Add("Content-Type", "application/json");
+            request.Content = "{}";
+
+            return message;
+        }
+
+        private AccessToken ParseAccessTokenFromResponse(Response response)
+        {
+            switch (response.Status)
+            {
+                case 200:
+                    try
+                    {
+                        var json = JsonDocument.Parse(response.Content);
+                        var accessTokenJson = json.RootElement.GetProperty("accessToken").GetRawText();
+                        var acsToken = JsonSerializer.Deserialize<AcsToken>(accessTokenJson);
+                        return new AccessToken(acsToken.token, acsToken.expiresOn);
+                    }
+                    catch (Exception)
+                    {
+                        throw new RequestFailedException(response);
+                    }
+                default:
+                    throw new RequestFailedException(response);
+            }
+        }
+
+        private class AcsToken
+        {
+            public string token { get; set; }
+            public DateTimeOffset expiresOn { get; set; }
+        }
+    }
+}

sdk/communication/Azure.Communication.Common/src/EntraTokenGuardPolicy.cs

@@ -0,0 +1,79 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Azure.Core;
+using Azure.Core.Pipeline;
+
+namespace Azure.Communication
+{
+    internal class EntraTokenGuardPolicy : HttpPipelinePolicy
+    {
+        private string _entraTokenCache;
+        private Response _responseCache;
+
+        public override void Process(HttpMessage message, ReadOnlyMemory<HttpPipelinePolicy> pipeline)
+        {
+            ProcessAsync(message, pipeline, async: false).EnsureCompleted();
+        }
+
+        public override ValueTask ProcessAsync(HttpMessage message, ReadOnlyMemory<HttpPipelinePolicy> pipeline)
+        {
+            return ProcessAsync(message, pipeline, async: true);
+        }
+
+        private async ValueTask ProcessAsync(HttpMessage message, ReadOnlyMemory<HttpPipelinePolicy> pipeline, bool async)
+        {
+            var (entraTokenCacheOutdated, token) = IsEntraTokenCacheOutdated(message);
+            if (entraTokenCacheOutdated || IsAcsTokenCacheOutdated())
+            {
+                _entraTokenCache = token;
+                if (async)
+                {
+                    await ProcessNextAsync(message, pipeline).ConfigureAwait(continueOnCapturedContext: false);
+                }
+                else
+                {
+                    ProcessNext(message, pipeline);
+                }
+                _responseCache = message.Response;
+            }
+            else
+            {
+                message.Response = _responseCache;
+                return;
+            }
+        }
+
+        private (bool CacheOutdated, string EntraToken) IsEntraTokenCacheOutdated(HttpMessage message)
+        {
+            var currentEntraToken = string.Empty;
+            message.Request.Headers.TryGetValue("Authorization", out currentEntraToken);
+            return (string.IsNullOrEmpty(_entraTokenCache) || currentEntraToken != _entraTokenCache, currentEntraToken);
+        }
+        private bool IsAcsTokenCacheOutdated()
+        {
+            return _responseCache == null || _responseCache.Status != 200 || !IsAccessTokenValid();
+        }
+
+        private bool IsAccessTokenValid()
+        {
+            try
+            {
+                var json = JsonDocument.Parse(_responseCache.Content);
+                var expiresOnString = json.RootElement
+                                          .GetProperty("accessToken")
+                                          .GetProperty("expiresOn")
+                                          .GetString();
+                var expiresOn = DateTimeOffset.Parse(expiresOnString);
+                return DateTimeOffset.UtcNow < expiresOn;
+            }
+            catch
+            {
+                return false;
+            }
+        }
+    }
+}