OAuth env variable names should match .net/python by sw-joelmut · Pull Request #872 · microsoft/Agents-for-js

sw-joelmut · 2026-01-15T17:45:07Z

Fixes #755

Description

This PR centralizes authorization options loading logic into the AuthorizationManager, providing a cleaner separation of concerns and unified configuration handling for all authorization handlers.

Key Changes

🔄 Renamed Authorization Type

Renamed agentic type to AgenticUserAuthorization for clarity
Backward compatibility maintained - agentic still works but shows deprecation warning

📦 Centralized Options Loading

Moved .env loading logic from individual handlers to AuthorizationManager
Handlers now receive fully-resolved options via constructor only
Consistent environment variable handling with both legacy and latest formats

🔧 Environment Variable Support

Format	Pattern
Latest	`AgentApplication__UserAuthorization__handlers__{id}__settings__{property}`
Legacy	`{id}_{property}` (deprecated)

✨ Improvements

Added loadScopes() utility for parsing comma-separated scope strings
Unified deprecation warning system for legacy environment variables
Better error messages when required options are missing
Environment variables are case-insensitive

Testing

The following image shows the samples working with legacy and latest settings.

- Renamed properties in AzureBotAuthorizationOptions for clarity and consistency. - Deprecated old properties in AzureBotAuthorizationOptions and provided new alternatives. - Updated environment variable mappings to reflect new property names. - Enhanced error handling for missing required options. - Added new utility function to load configuration from environment variables. - Introduced comprehensive tests for the AuthorizationManager to validate new configurations and ensure backward compatibility with legacy environment variables.

Copilot

Pull request overview

This PR standardizes OAuth environment variable naming conventions to align with .NET/Python SDKs and centralizes authorization configuration loading into the AuthorizationManager.

Changes:

Renamed authorization type from agentic to AgenticUserAuthorization with backward compatibility
Centralized environment variable loading from individual handlers to AuthorizationManager
Added support for both legacy and latest environment variable formats with case-insensitive matching

Reviewed changes

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

Show a summary per file

File	Description
packages/agents-hosting/src/app/auth/authorizationManager.ts	Centralized options loading logic and environment variable handling
packages/agents-hosting/src/app/auth/handlers/azureBotAuthorization.ts	Removed options loading from handler, now receives fully-resolved options
packages/agents-hosting/src/app/auth/handlers/agenticAuthorization.ts	Removed options loading from handler, updated type to support both old and new names
packages/agents-hosting/src/auth/authConfiguration.ts	Added new `env` utility function for case-insensitive environment variable loading
packages/agents-hosting/test/hosting/app/authorizationmanager.test.ts	Comprehensive test coverage for new centralized authorization manager
packages/agents-hosting/test/hosting/app/authorization.test.ts	Updated tests to use new property names

Comments suppressed due to low confidence (1)

packages/agents-hosting/test/hosting/app/authorization.test.ts:9

Corrected spelling of 'intitalize' to 'initialize' and 'underfined' to 'undefined'.

  it('should intitalize with underfined authorization', () => {

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

packages/agents-hosting/src/auth/authConfiguration.ts

packages/agents-hosting/src/app/auth/authorizationManager.ts

benbrown · 2026-01-20T17:15:39Z

packages/agents-hosting/src/app/auth/authorizationManager.ts

+      const format = legacyProperties
+        .map(([prop, value]) => `  ${this._envDefinition.latest.key(id, `__${prop}`)}=${value}`)
+        .join('\n')
+      logger.warn(this.prefix(id, 'Deprecated environment variables detected, update to the latest format: (case-insensitive)'), `[\n${format}\n]`)


would this log sensitive values?

Yes, it would, thank you for pointing that out, I will improve it so instead of showing the value, it shows a comment of the legacy property to replace. A second option could be applying obfuscation, so the user can reference the legacy property through the value, but i prefer the first option.

benbrown · 2026-01-20T17:20:41Z

packages/agents-hosting/src/app/auth/handlers/azureBotAuthorization.ts

-   * When using environment variables, this can be set using the `${authHandlerId}_connectionName` variable.
   */
-  name?: string,
+  azureBotOAuthConnectionName?: string,


is there backwards compat needed for this?

Yes, i moved all legacy properties at the bottom of the interface

benbrown · 2026-01-20T17:25:53Z

packages/agents-hosting/test/hosting/app/authorizationmanager.test.ts

+    const app = new AgentApplication({
+      storage: new MemoryStorage(),
+      authorization: {
+        testAuth: { name: undefined } // triggers legacy mode


is something like this required to trigger legacy mode, or does it just work as it used to?

No, it isn't necessary, it will detect the config or .env variables if they are legacy. I removed the name: undefined

benbrown · 2026-01-20T17:26:41Z

packages/agents-hosting/test/hosting/app/authorizationmanager.test.ts

+    const app = new AgentApplication({
+      storage: new MemoryStorage(),
+      authorization: {
+        testAuth: {}


Is this empty value now required somehow?

Defining an auth handler in the authorization config was always required, but now thinking of this, we could improve it by not being required if done from the .env.

benbrown · 2026-01-20T17:29:54Z

packages/agents-hosting/test/hosting/app/authorizationmanager.test.ts

+      storage: new MemoryStorage(),
+      authorization: {
+        testAuth: {
+          enableSso: false


was it always the case that we would merge environment variables + constructor options?

This seems a bit confusing to me, since the env variables are invisible this way.

Yes, it is confusing, this was already this way, merging the two.
I checked how .net does it, it has two overload constructors, one for loading from Config (appsetting.json) and one for manual (code), it uses one or the other, it doesnt combine the two.

Since we are changing to a new configuration, we could leave the legacy as is, and for the new, apply the same behavior, if there are settings in code, dont use .env, otherwise use .env.

I think it will be a good improvement, it happened to me many times that a sample had the 'azureBotOAuthConnectionName' set in the code, and i was using a different one in the .env and prioritized the code one.

…tions

sw-joelmut · 2026-02-03T16:23:09Z

Hi @benbrown, I pushed new changes, here is a brief summary:

Legacy options

Internally maps to the new options structure.

Legacy env

Depends on having runtime handlers declared as it does today.
Warning message when the process detects legacy env variables.
Error when runtime handlers are not declared.
Extracts handler id, option key (maps it to latest format), and value from the env to create the handler and options.

Latest env

AgentApplication.authorization config is no longer necessary to have the handler defined. If a runtime configuration is provided per handler, it will use it instead of latest env.
Supports case-insensitive env keys declaration, the value will not be altered, except for the 'type' property and 'scopes' (comma or whitespace separated)
Extracts handler id, option key, and value from the env to create the handler and options.

Internal changes and improvements

Different approach to read .env variables by using a 'parser', allowing to reduce code required, better structure of properties we are reading, and allowing conversion from legacy to latest env format.
Less .env variables and handlers iterations
Better flow from reading a .env to loading the information to a handlers array for latest processing.

Testing

sw-joelmut added 2 commits January 14, 2026 16:59

Improve clarity and readability

b74aae5

sw-joelmut requested review from benbrown and Copilot January 15, 2026 17:45

Merge branch 'main' into southworks/update/auth-env-loading

2a1fc00

Copilot started reviewing on behalf of sw-joelmut January 15, 2026 17:45 View session

Copilot AI reviewed Jan 15, 2026

View reviewed changes

Fix typos in parseScopes and env function assignments

09d80a5

sw-joelmut mentioned this pull request Jan 20, 2026

Implement auto signin handler #882

Open

benbrown reviewed Jan 20, 2026

View reviewed changes

sw-joelmut added 2 commits February 3, 2026 09:23

Merge branch 'main' into southworks/update/auth-env-loading

1279a3e

Improvements to the authorization configuration regarding new .env op…

af4c55d

…tions

sw-joelmut added 2 commits February 3, 2026 16:34

Merge branch 'main' into southworks/update/auth-env-loading

a6a8d26

Merge branch 'main' into southworks/update/auth-env-loading

f3f804f

Conversation

sw-joelmut commented Jan 15, 2026

Description

Key Changes

🔄 Renamed Authorization Type

📦 Centralized Options Loading

🔧 Environment Variable Support

✨ Improvements

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sw-joelmut commented Feb 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

sw-joelmut commented Feb 3, 2026 •

edited

Loading