Feat: add signin/failure invoke handling

[corinagum]

Resolves #346

Route and handle signin/failure invoke activities that Teams sends when SSO token exchange fails. Adds a system default handler that logs actionable warnings and emits error events, plus a signin.failure route for developer overrides.

Previously, when Teams sent a signin/failure invoke (e.g., due to an SSO misconfiguration), the SDKs silently swallowed the failure with no logging, no error events, and no developer notification. This made SSO configuration issues extremely difficult to diagnose.

User: hi
(No response from app)

The Problem

When a Teams app uses SSO (Single Sign-On) with a Token Exchange URL configured in the OAuth connection settings, Teams attempts a silent token exchange. If this fails -- for example, because the Entra app registration's "Expose an API" configuration doesn't match the Token Exchange URL -- Teams sends a signin/failure invoke activity with details like:

{
  "type": "invoke",
  "name": "signin/failure",
  "value": {
    "code": "resourcematchfailed",
    "message": "Resource match failed"
  }
}

Before this change, none of the three SDKs routed or handled this invoke. The failure was invisible to the user, SDK, and the developer. The user saw no sign-in card, no error message, and no indication of what went wrong.

Now, sign in failures with send a warning, emits error event, and return HTTP 200 by default. Developers can also register custom handlers if desired, for example:

C#:

app.OnFailure(async (context) =>
{
    var failure = context.Activity.Value;
    Console.WriteLine($"Sign-in failed: {failure.Code} - {failure.Message}");
    return new Response(HttpStatusCode.OK);
});

Example log on signin/failure:

[WARNING] @teams/app Sign-in failed for user 29:xxxxx
  in conversation a:1_xxxxx:
  resourcematchfailed — Resource match failed.
  If the code is 'resourcematchfailed', verify that your Entra app registration has 'Expose an API'
  configured with the correct Application ID URI matching your OAuth connection's Token Exchange URL.

Note that the default behavior will still appear to fail silently for the user. There will be logs, but it will be up to the developer to determine how the user experiences the sign-in failure. 'resourcematchfailed' is an example of a setup error, however, and should not be an error that a 'real' user experiences. If desired, we could potentially modify the default behavior to send something to the user, but I'm disinclined to make that decision on the behalf of the developer.

Feature work tested and verified in C#, PY, and TS.

[Copilot]

Pull request overview

This PR adds comprehensive handling for signin/failure invoke activities that Teams sends when SSO token exchange fails. Previously, these failures were silently swallowed with no logging or developer notification, making SSO configuration issues extremely difficult to diagnose.

Changes:

• Adds new Failure data model and FailureActivity classes for representing signin/failure invokes
• Integrates signin/failure into the activity routing and serialization infrastructure
• Provides OnFailure extension methods with 6 overloads for custom handler registration
• Implements a default system handler that logs actionable warnings and emits error events

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
Libraries/Microsoft.Teams.Api/SignIn/Failure.cs	New data model for sign-in failure information (code and message)
Libraries/Microsoft.Teams.Api/Activities/Invokes/SignIn/FailureActivity.cs	New activity class representing signin/failure invoke activities
Libraries/Microsoft.Teams.Api/Activities/Invokes/SignInActivity.cs	Adds ToFailure() method and serialization support for FailureActivity
Libraries/Microsoft.Teams.Apps/Activities/Invokes/SignIn/FailureActivity.cs	Extension methods providing 6 OnFailure overloads for handler registration
Libraries/Microsoft.Teams.Apps/AppRouting.cs	Default handler that logs warnings with actionable guidance and emits error events
Libraries/Microsoft.Teams.Apps/App.cs	Registers the default OnFailureActivity handler during app initialization
Tests/Microsoft.Teams.Api.Tests/Activities/Invokes/SignIn/FailureSignInActivityTests.cs	Comprehensive tests for serialization/deserialization of FailureActivity
Tests/Microsoft.Teams.Api.Tests/Json/Activity/Invokes/SignInFailureActivity.json	Test fixture JSON for signin/failure activity

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[singhk97]

nit: OnFailure handler can be vague and confusing. Failure to send a message? failure to validate an incoming token? What's the difference between OnError and OnFailure handlers?

I can see how OnFailureActivity makes sense because it's part of the SignIn namespace so that doesn't seem to be as confusing.

[corinagum]

How about, to keep it explicit with the route, OnSigninFailure?

I'd prefer not to do OnSigninFailureActivity just because of length, but if that's your preference I'm not opposed. Thoughts?

[rido-min]

@corinagum how is this PR related to #329 ? can we merge this two?

[corinagum]

@rido-min Thanks for pointing it out, I hadn't looked at the PR. Will do so and get back to you.