feat: add multi-connection OAuth registry and flow APIs

[Lily Du (lilyydu)]

Summary

This PR adds the public registry and flow APIs for using multiple named OAuth connections in teams.py.

It is stacked on #554 and is intentionally limited to the registration and connection-bound API layer. Callback routing, pending sign-in attribution, and state-backed deduplication are deferred to follow-up PRs.

The API follows the C# SDK's OAuthFlow / AddOAuthFlow(...) model while remaining additive and backward-compatible with the existing app-level default OAuth connection.

What changed

Register named OAuth flows

Added OAuthFlow and a case-insensitive, insertion-ordered OAuthFlowRegistry.

github = app.add_oauth_flow(
    "github",
    oauth_card_text="Sign in with GitHub",
    sign_in_button_text="Continue",
)

graph = app.add_oauth_flow("graph")

same_github_flow = app.get_oauth_flow("GITHUB")

• App.add_oauth_flow(...) registers and returns an OAuthFlow.
• App.get_oauth_flow(...) retrieves a registered flow case-insensitively.
• Duplicate connection names raise ValueError case-insensitively.
• Missing connections raise ValueError with the registered connection names.
• OAuthFlow and OAuthFlowRegistry are exported from microsoft_teams.apps.

Add connection-bound flow operations

Each OAuthFlow delegates OAuth operations to its own connection:

await github.sign_in(ctx)
await github.sign_out(ctx)

token = await github.get_token(ctx)
signed_in = await github.is_signed_in(ctx)

OAuthFlow.sign_in(...) preserves caller-provided card text and button text but always forces the flow's connection name, preventing options for one connection from being used through another flow.

Flows also expose on_signin(...) and on_signin_failure(...) handler registration. Invocation of those per-flow handlers will be wired by the callback-routing layer in a follow-up PR.

Add per-connection ActivityContext helpers

• ctx.sign_out(connection_name=...) signs out a specific connection.
• ctx.get_user_token(connection_name=...) retrieves the token for a specific connection.
• Omitting connection_name preserves the existing default-connection behavior.
• get_user_token(...) returns None only when Token Service returns 404.
• Non-404 Token Service failures propagate instead of being reported as a signed-out user.
• ctx.get_token_status() makes one request and returns status for all bot OAuth connections.

Add a structured sign-in failure event

Added SignInFailureEvent, containing:

• the activity context;
• connection name;
• failure code;
• failure message.

The existing OAuth failure handler emits both the existing ErrorEvent for backward compatibility and the new sign_in_failure event for structured handling.

Backward compatibility

Existing single-connection OAuth APIs continue to use the app-level default connection when no connection name is provided. Registering flows is optional, so existing applications do not need to change.

Deferred to follow-up PRs

This PR does not yet:

• route token exchange, verify-state, or failure callbacks to a registered flow;
• invoke per-flow success or failure handlers;
• persist pending sign-in attribution in turn state;
• add state-backed callback deduplication;
• update the OAuth example to demonstrate end-to-end multi-connection behavior.

[Copilot]

Pull request overview

Adds first-class multi-connection OAuth support to the Teams Python SDK by introducing a named OAuth flow registry and connection-bound OAuth helpers/events, while keeping the existing default-connection behavior intact.

Changes:

• Added OAuthFlow and a case-insensitive, insertion-ordered OAuthFlowRegistry, plus App.add_oauth_flow(...) / App.get_oauth_flow(...).
• Added connection-bound ActivityContext OAuth helpers: sign_out(connection_name=...), get_user_token(connection_name=...), and get_token_status().
• Added a structured SignInFailureEvent and wired it into the existing sign-in failure handling (while preserving the legacy ErrorEvent).

Reviewed changes

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

Show a summary per file

File	Description
packages/apps/tests/test_oauth_flow.py	Adds coverage for OAuthFlow handler registration, flow operations, registry behavior, and App integration.
packages/apps/tests/test_app_oauth.py	Updates tests to assert both legacy error emission and new sign_in_failure event emission.
packages/apps/tests/test_activity_context.py	Adds tests for per-connection token helpers, 404 vs non-404 behavior, and token status retrieval.
packages/apps/src/microsoft_teams/apps/routing/activity_context.py	Implements per-connection sign_out, get_user_token, and get_token_status on the turn context.
packages/apps/src/microsoft_teams/apps/routing/init.py	Re-exports SignInOptions for external flow APIs/tests.
packages/apps/src/microsoft_teams/apps/oauth_flow.py	Introduces OAuthFlow and OAuthFlowRegistry types and flow-level operations/handlers.
packages/apps/src/microsoft_teams/apps/events/types.py	Adds SignInFailureEvent dataclass to the event type set.
packages/apps/src/microsoft_teams/apps/events/registry.py	Registers sign_in_failure as a core event type and maps it to SignInFailureEvent.
packages/apps/src/microsoft_teams/apps/events/init.py	Exports SignInFailureEvent from the events package.
packages/apps/src/microsoft_teams/apps/app.py	Adds an internal OAuth flow registry and public App-level add/get flow APIs.
packages/apps/src/microsoft_teams/apps/app_oauth.py	Emits the new sign_in_failure structured event alongside the existing error event on failure.
packages/apps/src/microsoft_teams/apps/init.py	Exposes OAuthFlow and OAuthFlowRegistry from microsoft_teams.apps.
packages/api/src/microsoft_teams/api/clients/user/params.py	Makes include_filter optional so token status can be requested for all connections in one call.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Corina (corinagum)]

app_oauth.py:64-69 says "Token verification will likely fail" With registered non-default connections now being supported, SSO will send a false alarm. Maybe update to check whether a flow is registered for that connection?