Account Linking Url: Combined Auth Flow

Libraries/Microsoft.Teams.Api/Auth/ClientCredentials.cs

@@ -5,6 +5,10 @@
 
 namespace Microsoft.Teams.Api.Auth;
 
+/// <summary>
+/// ClientId / ClientSecret based credentials
+/// https://learn.microsoft.com/en-us/microsoft-365/agents-sdk/azure-bot-create-single-secret
+/// </summary>
 public class ClientCredentials : IHttpCredentials
 {
     public string ClientId { get; set; }

Libraries/Microsoft.Teams.Api/Auth/TokenCredentials.cs

@@ -7,6 +7,12 @@ namespace Microsoft.Teams.Api.Auth;
 
 public delegate Task<ITokenResponse> TokenFactory(string? tenantId, params string[] scopes);
 
+/// <summary>
+/// Provide a <code>TokenFactory</code> that will be invoked whenever
+/// the application needs a token.
+/// TokenCredentials should be used with 3rd party packages like MSAL/Azure.Identity
+/// to authenticate for any Federated/Managed Identity scenarios.
+/// </summary>
 public class TokenCredentials : IHttpCredentials
 {
     public string ClientId { get; set; }
@@ -26,7 +32,7 @@ public TokenCredentials(string clientId, string tenantId, TokenFactory token)
         Token = token;
     }
 
-    public async Task<ITokenResponse> Resolve(IHttpClient _client, string[] scopes, CancellationToken cancellationToken = default)
+    public async Task<ITokenResponse> Resolve(IHttpClient _, string[] scopes, CancellationToken cancellationToken = default)
     {
         return await Token(TenantId, scopes);
     }

Libraries/Microsoft.Teams.Api/Clients/ActivityClient.cs

@@ -32,7 +32,7 @@ public ActivityClient(string serviceUrl, IHttpClientFactory factory, Cancellatio
         ServiceUrl = serviceUrl;
     }
 
-    public async Task<Resource?> CreateAsync(string conversationId, IActivity activity, bool isTargeted = false)
+    public virtual async Task<Resource?> CreateAsync(string conversationId, IActivity activity, bool isTargeted = false)
     {
         var url = $"{ServiceUrl}v3/conversations/{conversationId}/activities";
         if (isTargeted)
@@ -50,7 +50,7 @@ public ActivityClient(string serviceUrl, IHttpClientFactory factory, Cancellatio
         return body;
     }
 
-    public async Task<Resource?> UpdateAsync(string conversationId, string id, IActivity activity, bool isTargeted = false)
+    public virtual async Task<Resource?> UpdateAsync(string conversationId, string id, IActivity activity, bool isTargeted = false)
     {
         var url = $"{ServiceUrl}v3/conversations/{conversationId}/activities/{id}";
         if (isTargeted)
@@ -68,7 +68,7 @@ public ActivityClient(string serviceUrl, IHttpClientFactory factory, Cancellatio
         return body;
     }
 
-    public async Task<Resource?> ReplyAsync(string conversationId, string id, IActivity activity, bool isTargeted = false)
+    public virtual async Task<Resource?> ReplyAsync(string conversationId, string id, IActivity activity, bool isTargeted = false)
     {
         activity.ReplyToId = id;
 
@@ -88,7 +88,7 @@ public ActivityClient(string serviceUrl, IHttpClientFactory factory, Cancellatio
         return body;
     }
 
-    public async Task DeleteAsync(string conversationId, string id, bool isTargeted = false)
+    public virtual async Task DeleteAsync(string conversationId, string id, bool isTargeted = false)
     {
         var url = $"{ServiceUrl}v3/conversations/{conversationId}/activities/{id}";
         if (isTargeted)

Libraries/Microsoft.Teams.Api/Clients/BotClient.cs

@@ -8,7 +8,7 @@ namespace Microsoft.Teams.Api.Clients;
 public class BotClient : Client
 {
     public virtual BotTokenClient Token { get; }
-    public BotSignInClient SignIn { get; }
+    public virtual BotSignInClient SignIn { get; }
 
     public BotClient() : this(default)
     {

Libraries/Microsoft.Teams.Api/Clients/BotSignInClient.cs

@@ -27,7 +27,7 @@ public BotSignInClient(IHttpClientFactory factory, CancellationToken cancellatio
 
     }
 
-    public async Task<string> GetUrlAsync(GetUrlRequest request)
+    public virtual async Task<string> GetUrlAsync(GetUrlRequest request)
     {
         var query = QueryString.Serialize(request);
         var req = HttpRequest.Get(
@@ -38,7 +38,7 @@ public async Task<string> GetUrlAsync(GetUrlRequest request)
         return res.Body;
     }
 
-    public async Task<SignIn.UrlResponse> GetResourceAsync(GetResourceRequest request)
+    public virtual async Task<SignIn.UrlResponse> GetResourceAsync(GetResourceRequest request)
     {
         var query = QueryString.Serialize(request);
         var req = HttpRequest.Get(

Libraries/Microsoft.Teams.Api/Clients/BotTokenClient.cs

@@ -10,7 +10,7 @@ public class BotTokenClient : Client
     public static readonly string BotScope = "https://api.botframework.com/.default";
     public static readonly string GraphScope = "https://graph.microsoft.com/.default";
 
-    public BotTokenClient() : this(default)
+    public BotTokenClient() : base()
     {
 
     }
@@ -40,7 +40,7 @@ public virtual async Task<ITokenResponse> GetAsync(IHttpCredentials credentials,
         return await credentials.Resolve(http ?? _http, [BotScope], _cancellationToken);
     }
 
-    public async Task<ITokenResponse> GetGraphAsync(IHttpCredentials credentials, IHttpClient? http = null)
+    public virtual async Task<ITokenResponse> GetGraphAsync(IHttpCredentials credentials, IHttpClient? http = null)
     {
         return await credentials.Resolve(http ?? _http, [GraphScope], _cancellationToken);
     }

Libraries/Microsoft.Teams.Api/Clients/ConversationClient.cs

@@ -11,8 +11,8 @@ namespace Microsoft.Teams.Api.Clients;
 public class ConversationClient : Client
 {
     public readonly string ServiceUrl;
-    public readonly ActivityClient Activities;
-    public readonly MemberClient Members;
+    public virtual ActivityClient Activities { get; }
+    public virtual MemberClient Members { get; }
 
     public ConversationClient(string serviceUrl, CancellationToken cancellationToken = default) : base(cancellationToken)
     {
@@ -42,7 +42,7 @@ public ConversationClient(string serviceUrl, IHttpClientFactory factory, Cancell
         Members = new MemberClient(serviceUrl, _http, cancellationToken);
     }
 
-    public async Task<ConversationResource> CreateAsync(CreateRequest request)
+    public virtual async Task<ConversationResource> CreateAsync(CreateRequest request)
     {
         var req = HttpRequest.Post($"{ServiceUrl}v3/conversations", body: request);
         var res = await _http.SendAsync<ConversationResource>(req, _cancellationToken);

Libraries/Microsoft.Teams.Api/Clients/MeetingClient.cs

@@ -32,14 +32,14 @@ public MeetingClient(string serviceUrl, IHttpClientFactory factory, Cancellation
         ServiceUrl = serviceUrl;
     }
 
-    public async Task<Meeting> GetByIdAsync(string id)
+    public virtual async Task<Meeting> GetByIdAsync(string id)
     {
         var request = HttpRequest.Get($"{ServiceUrl}v1/meetings/{id}");
         var response = await _http.SendAsync<Meeting>(request, _cancellationToken);
         return response.Body;
     }
 
-    public async Task<MeetingParticipant> GetParticipantAsync(string meetingId, string id)
+    public virtual async Task<MeetingParticipant> GetParticipantAsync(string meetingId, string id)
     {
         var request = HttpRequest.Get($"{ServiceUrl}v1/meetings/{meetingId}/participants/{id}");
         var response = await _http.SendAsync<MeetingParticipant>(request, _cancellationToken);

Libraries/Microsoft.Teams.Api/Clients/MemberClient.cs

@@ -29,21 +29,21 @@ public MemberClient(string serviceUrl, IHttpClientFactory factory, CancellationT
         ServiceUrl = serviceUrl;
     }
 
-    public async Task<List<Account>> GetAsync(string conversationId)
+    public virtual async Task<List<Account>> GetAsync(string conversationId)
     {
         var request = HttpRequest.Get($"{ServiceUrl}v3/conversations/{conversationId}/members");
         var response = await _http.SendAsync<List<Account>>(request, _cancellationToken);
         return response.Body;
     }
 
-    public async Task<Account> GetByIdAsync(string conversationId, string memberId)
+    public virtual async Task<Account> GetByIdAsync(string conversationId, string memberId)
     {
         var request = HttpRequest.Get($"{ServiceUrl}v3/conversations/{conversationId}/members/{memberId}");
         var response = await _http.SendAsync<Account>(request, _cancellationToken);
         return response.Body;
     }
 
-    public async Task DeleteAsync(string conversationId, string memberId)
+    public virtual async Task DeleteAsync(string conversationId, string memberId)
     {
         var request = HttpRequest.Delete($"{ServiceUrl}v3/conversations/{conversationId}/members/{memberId}");
         await _http.SendAsync(request, _cancellationToken);

Libraries/Microsoft.Teams.Api/Clients/TeamClient.cs

@@ -29,14 +29,14 @@ public TeamClient(string serviceUrl, IHttpClientFactory factory, CancellationTok
         ServiceUrl = serviceUrl;
     }
 
-    public async Task<Team> GetByIdAsync(string id)
+    public virtual async Task<Team> GetByIdAsync(string id)
     {
         var request = HttpRequest.Get($"{ServiceUrl}v3/teams/{id}");
         var response = await _http.SendAsync<Team>(request, _cancellationToken);
         return response.Body;
     }
 
-    public async Task<List<Channel>> GetConversationsAsync(string id)
+    public virtual async Task<List<Channel>> GetConversationsAsync(string id)
     {
         var request = HttpRequest.Get($"{ServiceUrl}v3/teams/{id}/conversations");
         var response = await _http.SendAsync<List<Channel>>(request, _cancellationToken);

Libraries/Microsoft.Teams.Api/Clients/UserClient.cs

@@ -7,7 +7,12 @@ namespace Microsoft.Teams.Api.Clients;
 
 public class UserClient : Client
 {
-    public UserTokenClient Token { get; }
+    public virtual UserTokenClient Token { get; }
+
+    public UserClient() : base()
+    {
+        Token = new UserTokenClient(_http, _cancellationToken);
+    }
 
     public UserClient(CancellationToken cancellationToken = default) : base(cancellationToken)
     {

Libraries/Microsoft.Teams.Api/Clients/UserTokenClient.cs

@@ -15,6 +15,11 @@ public class UserTokenClient : Client
         DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
     };
 
+    public UserTokenClient() : base()
+    {
+
+    }
+
     public UserTokenClient(CancellationToken cancellationToken = default) : base(cancellationToken)
     {
 
@@ -35,38 +40,38 @@ public UserTokenClient(IHttpClientFactory factory, CancellationToken cancellatio
 
     }
 
-    public async Task<Token.Response> GetAsync(GetTokenRequest request)
+    public virtual async Task<Token.Response> GetAsync(GetTokenRequest request)
     {
         var query = QueryString.Serialize(request);
         var req = HttpRequest.Get($"https://token.botframework.com/api/usertoken/GetToken?{query}");
         var res = await _http.SendAsync<Token.Response>(req, _cancellationToken);
         return res.Body;
     }
 
-    public async Task<IDictionary<string, Token.Response>> GetAadAsync(GetAadTokenRequest request)
+    public virtual async Task<IDictionary<string, Token.Response>> GetAadAsync(GetAadTokenRequest request)
     {
         var query = QueryString.Serialize(request);
         var req = HttpRequest.Post($"https://token.botframework.com/api/usertoken/GetAadTokens?{query}", body: request);
         var res = await _http.SendAsync<IDictionary<string, Token.Response>>(req, _cancellationToken);
         return res.Body;
     }
 
-    public async Task<IList<Token.Status>> GetStatusAsync(GetTokenStatusRequest request)
+    public virtual async Task<IList<Token.Status>> GetStatusAsync(GetTokenStatusRequest request)
     {
         var query = QueryString.Serialize(request);
         var req = HttpRequest.Get($"https://token.botframework.com/api/usertoken/GetTokenStatus?{query}");
         var res = await _http.SendAsync<IList<Token.Status>>(req, _cancellationToken);
         return res.Body;
     }
 
-    public async Task SignOutAsync(SignOutRequest request)
+    public virtual async Task SignOutAsync(SignOutRequest request)
     {
         var query = QueryString.Serialize(request);
         var req = HttpRequest.Delete($"https://token.botframework.com/api/usertoken/SignOut?{query}");
         await _http.SendAsync(req, _cancellationToken);
     }
 
-    public async Task<Token.Response> ExchangeAsync(ExchangeTokenRequest request)
+    public virtual async Task<Token.Response> ExchangeAsync(ExchangeTokenRequest request)
     {
         var query = QueryString.Serialize(new
         {

Libraries/Microsoft.Teams.Apps/AppBuilder.cs

@@ -92,9 +92,16 @@ public AppBuilder AddPlugin(Func<Task<IPlugin>> @delegate)
         return this;
     }
 
+    public AppBuilder AddOAuth(OAuthSettings oauthSettings)
+    {
+        _options.OAuth = oauthSettings;
+        return this;
+    }
+
     public AppBuilder AddOAuth(string defaultConnectionName)
     {
-        _options.OAuth = new OAuthSettings(defaultConnectionName);
+        _options.OAuth ??= new();
+        _options.OAuth.DefaultConnectionName = defaultConnectionName;
         return this;
     }
 

Libraries/Microsoft.Teams.Apps/AppOptions.cs

@@ -7,14 +7,49 @@ namespace Microsoft.Teams.Apps;
 
 public class AppOptions
 {
+    /// <summary>
+    /// The applications optional storage provider that allows
+    /// the application to access shared dependencies.
+    /// </summary>
     public IServiceProvider? Provider { get; set; }
+
+    /// <summary>
+    /// The applications optional ILogger instance.
+    /// </summary>
     public Common.Logging.ILogger? Logger { get; set; }
+
+    /// <summary>
+    /// The applications optional IStorage instance.
+    /// </summary>
     public Common.Storage.IStorage<string, object>? Storage { get; set; }
+
+    /// <summary>
+    /// When provided, the application will use this <code>IHttpClient</code> instance
+    /// to send all http requests.
+    /// </summary>
     public Common.Http.IHttpClient? Client { get; set; }
+
+    /// <summary>
+    /// When provided, the application will use this <code>IHttpClientFactory</code> to
+    /// initialize a new client whenever needed.
+    /// </summary>
     public Common.Http.IHttpClientFactory? ClientFactory { get; set; }
+
+    /// <summary>
+    /// When provided, the application will use these credentials to resolve tokens it
+    /// uses to make API requests.
+    /// </summary>
     public Common.Http.IHttpCredentials? Credentials { get; set; }
+
+    /// <summary>
+    /// A list of plugins to import into the application.
+    /// </summary>
     public IList<IPlugin> Plugins { get; set; } = [];
-    public OAuthSettings OAuth { get; set; } = new OAuthSettings();
+
+    /// <summary>
+    /// User <code>OAuth</code> settings for the deferred (User) auth flows.
+    /// </summary>
+    public OAuthSettings OAuth { get; set; } = new();
 
     public AppOptions()
     {

Libraries/Microsoft.Teams.Apps/AppRouting.cs

@@ -154,7 +154,11 @@ await Events.Emit(
                     Token = res
                 }
             );
-            return new Response(HttpStatusCode.OK);
+
+            return new Response(HttpStatusCode.OK, OAuth.AccountLinkingUrl is null ? null : new
+            {
+                accountLinkingUrl = OAuth.AccountLinkingUrl
+            });
         }
         catch (HttpException ex)
         {

Libraries/Microsoft.Teams.Apps/Contexts/Context.cs

@@ -112,6 +112,15 @@ public partial interface IContext<TActivity> where TActivity : IActivity
     /// </summary>
     public Task<object?> Next();
 
+    /// <summary>
+    /// Called to continue the chain of route handlers using the specified context instance.
+    /// Use this overload when you want to invoke the next handler with a different or wrapped
+    /// <see cref="IContext{TActivity}"/> than the current one; if not called, no other handlers
+    /// in the sequence will be executed.
+    /// </summary>
+    /// <param name="context">The context to pass to the next handler in the chain.</param>
+    public Task<object?> Next(IContext<TActivity> context);
+
     /// <summary>
     /// convert the context to that of another activity type
     /// </summary>
@@ -168,6 +177,7 @@ public void Deconstruct(out string appId, out ILogger log, out ApiClient api, ou
     }
 
     public Task<object?> Next() => OnNext(ToActivityType());
+    public Task<object?> Next(IContext<TActivity> context) => OnNext(context.ToActivityType());
     public IContext<IActivity> ToActivityType() => ToActivityType<IActivity>();
     public IContext<TToActivity> ToActivityType<TToActivity>() where TToActivity : IActivity
     {

Libraries/Microsoft.Teams.Apps/OAuthSettings.cs

@@ -1,7 +1,20 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-public class OAuthSettings(string? connectionName = "graph")
+namespace Microsoft.Teams.Apps;
+
+/// <summary>
+/// Settings for Deferred (User) auth flows
+/// </summary>
+public class OAuthSettings
 {
-    public string DefaultConnectionName { get; set; } = connectionName;
+    /// <summary>
+    /// The default connection name to use
+    /// </summary>
+    public string DefaultConnectionName { get; set; } = "graph";
+
+    /// <summary>
+    /// Url used for client to perform tab auth and link the NAA account to the bot login account.
+    /// </summary>
+    public string? AccountLinkingUrl { get; set; }
 }