Feat: add signin/failure invoke handling

[corinagum]

Resolves #285

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:

Python:

@app.on_signin_failure()
async def handle_signin_failure(ctx):
    failure = ctx.activity.value
    print(f"Sign-in failed: {failure.code} - {failure.message}")

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

Adds first-class routing/handling for Teams signin/failure invoke activities in the Python Apps SDK so SSO token-exchange failures are no longer silently swallowed, and developers can attach custom handlers.

Changes:

• Add a new signin.failure route configuration and App.on_signin_failure() registration method.
• Introduce a default OauthHandlers.sign_in_failure handler that logs and emits an "error" event.
• Add unit + routing/middleware-chain integration tests for signin/failure.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/apps/src/microsoft_teams/apps/app.py	Registers the default signin/failure handler during app initialization.
packages/apps/src/microsoft_teams/apps/app_oauth.py	Implements default signin/failure handling (logging + error event emission).
packages/apps/src/microsoft_teams/apps/routing/activity_route_configs.py	Adds signin.failure to ACTIVITY_ROUTES with an invoke selector for name == "signin/failure".
packages/apps/src/microsoft_teams/apps/routing/generated_handlers.py	Adds on_signin_failure() decorator/overloads to register handlers for the new route.
packages/apps/tests/test_app_oauth.py	Adds tests covering default handler behavior and routing/middleware-chain execution for signin/failure.

[Copilot]

sign_in_failure explicitly returns InvokeResponse(status=200). Since process_activity() already wraps a None middleware result into InvokeResponse(status=200, body=None), this return is redundant and (because the middleware chain overwrites the final response with the outer handler’s return) it prevents developer on_signin_failure handlers from returning a different InvokeResponse if they need to. Consider returning None here (while still logging/emitting) so the default stays 200 but developer handlers can optionally control the invoke response.

Suggested change

	return InvokeResponse(status=200)
	return None