Implement auto signin handler

[sw-joelmut]

Fixes #857

Important

This PR will most likely conflict with PR #872

Description

This PR adds automatic sign-in capability to the UserAuthorization flow, allowing users to be automatically authenticated when first interacting with the application.
Additionally, the authorization configuration changed to include this feature and stays close to .NET settings.

New userAuthorization configuration options:

• autoSignIn - A selector function to enable/disable automatic sign-in per context
• defaultHandlerName - Specifies which handler to use for auto sign-in
• handlers - New structured format for configuring authorization handlers

Environment variables support:

• AGENTAPPLICATION__USERAUTHORIZATION__DEFAULTHANDLERNAME
• AGENTAPPLICATION__USERAUTHORIZATION__AUTOSIGNIN

Example usage:

userAuthorization: {
  defaultHandlerName: 'graph',
  autoSignIn: () => true, // Enabled for all contexts
  handlers: {
    graph: {
      settings: { text: 'Sign in with Microsoft Graph', title: 'Graph Sign In' }
    },
    github: {
      settings: { text: 'Sign in with GitHub', title: 'GitHub Sign In' }
    }
  }
}

⚠️ Deprecations

Deprecated	Replacement
AgentApplicationOptions.authorization	AgentApplicationOptions.userAuthorization
AgentApplicationBuilder.withAuthorization(AuthorizationOptions)	AgentApplicationBuilder.withAuthorization(UserAuthorizationOptions)
AuthorizationOptions type (flat structure)	UserAuthorizationOptions with nested handlers config

Migration example:

// ❌ Deprecated
authorization: {
  graph: { text: '...', title: '...' },
  github: { text: '...', title: '...' },
}

// ✅ New format
userAuthorization: {
  defaultHandlerName: 'graph',
  autoSignIn: () => true,
  handlers: {
    graph: {
      settings: { text: '...', title: '...' }
    },
    github: {
      settings: { text: '...', title: '...' }
    },
  }
}

Testing

The following image shows the feature working.

[Copilot]

Pull request overview

This PR implements automatic sign-in functionality for the UserAuthorization flow, allowing users to be automatically authenticated on first interaction with the application. The implementation introduces a new structured configuration format (userAuthorization) while maintaining backward compatibility with the legacy authorization format.

Changes:

• Added new UserAuthorizationOptions interface with autoSignIn, defaultHandlerName, and handlers properties
• Implemented auto sign-in logic in AuthorizationManager.process() that uses the default or first available handler when enabled
• Deprecated the flat authorization configuration in favor of nested userAuthorization.handlers structure
• Added environment variable support for AGENTAPPLICATION__USERAUTHORIZATION__DEFAULTHANDLERNAME and AGENTAPPLICATION__USERAUTHORIZATION__AUTOSIGNIN

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/agents-hosting/src/app/auth/types.ts	Defines new types and interfaces for UserAuthorizationOptions, AuthorizationHandlers, and AutoSignInSelector; deprecates old AuthorizationOptions type
packages/agents-hosting/src/app/auth/authorizationManager.ts	Implements normalizeOptions() for backward compatibility, adds auto sign-in logic in process() method, improves type validation
packages/agents-hosting/src/app/agentApplicationOptions.ts	Adds userAuthorization property and deprecates authorization property
packages/agents-hosting/src/app/agentApplicationBuilder.ts	Adds overloaded withAuthorization() method with type guard to support both old and new formats
packages/agents-hosting/src/app/agentApplication.ts	Updates authorization checks to support both userAuthorization and authorization properties
packages/agents-hosting/test/hosting/app/authorization.test.ts	Updates error message assertion to match new implementation

---

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