Add initial version of Entra authentication sidecar by matthewmeyer · Pull Request #424 · microsoft/Agents-for-python

matthewmeyer · 2026-06-18T21:26:09Z

This pull request introduces a new authentication package, microsoft-agents-authentication-entra-auth-sidecar, which enables credential-free Entra ID Agent ID authentication via a sidecar process. The PR includes the package’s initial implementation, updates documentation to reference and describe the new package, and adds configuration and utility code to support robust environment variable handling and token expiry logic.

Key changes:

New authentication package: Entra Auth Sidecar

Added the new package microsoft-agents-authentication-entra-auth-sidecar, including its initial implementation, license, and manifest. This package provides credential-free Entra ID Agent ID authentication via a sidecar and exposes SidecarAuth, SidecarHttpClient, and related models and errors. [1] [2] [3] [4] [5] [6]

Documentation updates

Updated README.md and CLAUDE.md to document the new package, its purpose, usage, and how it fits into the SDK’s modular architecture. The documentation now includes the new package in the authentication layer and lists its features and install instructions. [1] [2] [3] [4] [5]

Build and install process

Modified the GitHub Actions workflow (.github/workflows/python-package.yml) and editable install instructions to include the new package in the build and installation steps. [1] [2]

Configuration and utility enhancements

Added a shared utility module microsoft_agents/activity/config/_coercion.py that provides robust helpers for coercing environment variable values to bool, int, and float, ensuring consistent and safe configuration parsing across the SDK.

These changes collectively introduce a new authentication mechanism, ensure it is properly documented and integrated into the build system, and improve configuration handling across the SDK.

Copilot

Pull request overview

This PR introduces a new authentication provider package (microsoft-agents-authentication-entra-auth-sidecar) that delegates outbound token acquisition to the Microsoft Entra ID Agent Container (sidecar), and extends hosting-core to better support provider-agnostic configuration/routing (including MSAL and non-MSAL providers).

Changes:

Added the Entra Auth Sidecar authentication library (client, provider, settings/models, errors) plus tests and a runnable sample.
Introduced provider-agnostic hosting-core primitives (ConnectionManager, ConnectionSettingsBase) and updated MSAL + connector-client factory logic to work with non-MSAL providers.
Added shared env-value coercion helpers (coerce_bool/int/float) and updated docs/build setup to include the new package.

Reviewed changes

Copilot reviewed 39 out of 40 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/hosting_core/test_rest_channel_service_client_factory.py	Adds coverage for agentic token retrieval when providers expose `configuration` instead of MSAL internals.
tests/hosting_core/test_connection_settings_base.py	Tests new provider-agnostic `ConnectionSettingsBase` binding behavior.
tests/hosting_core/test_connection_manager.py	Tests new generic `ConnectionManager` routing behavior across multiple connections/map entries.
tests/hosting_core/test_auth_configuration.py	Adds tests for new .NET-aligned aliases and safe boolean coercion.
tests/authentication_entra_auth_sidecar/test_token_expiry.py	Validates JWT `exp` parsing and fallback lifetime logic.
tests/authentication_entra_auth_sidecar/test_sidecar_http_client.py	Exercises sidecar HTTP URL validation, query building, retries, and error shaping.
tests/authentication_entra_auth_sidecar/test_sidecar_auth.py	Validates SidecarAuth mapping and caching semantics.
tests/authentication_entra_auth_sidecar/test_settings.py	Validates settings normalization + env end-to-end flow into provider construction.
tests/authentication_entra_auth_sidecar/init.py	Test package marker for the sidecar auth tests.
tests/activity/test_config_coercion.py	Adds tests for shared env coercion helpers.
test_samples/entra_sidecar/requirements.txt	Sample dependencies for running the Entra sidecar demo.
test_samples/entra_sidecar/README.md	Usage/config documentation for the Entra sidecar sample.
test_samples/entra_sidecar/env.TEMPLATE	Template env config for the Entra sidecar sample (including token validation toggle).
test_samples/entra_sidecar/agent.py	Runnable aiohttp agent sample wired to `SidecarAuth` via generic `ConnectionManager`.
scripts/dev_setup.sh	Includes editable install for the new sidecar auth library.
scripts/dev_setup.ps1	Includes editable install for the new sidecar auth library.
README.md	Adds the new PyPI package to the top-level package list.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/rest_channel_service_client_factory.py	Makes agentic token retrieval provider-agnostic (`_msal_configuration` vs `configuration`).
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/connection_settings_base.py	Adds base provider-agnostic connection settings model + binding helpers.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/connection_manager.py	Adds generic connection manager that dispatches to any `AccessTokenProviderBase`.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/auth_types.py	Adds `EntraAuthSideCar` auth type enum value.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/agent_auth_configuration.py	Adds alias keys, safe boolean coercion, and snake_case read-only aliases.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/init.py	Re-exports new `ConnectionManager` and `ConnectionSettingsBase`.
libraries/microsoft-agents-hosting-core/microsoft_agents/hosting/core/init.py	Re-exports new `ConnectionManager` and `ConnectionSettingsBase` at the core package level.
libraries/microsoft-agents-authentication-msal/microsoft_agents/authentication/msal/msal_connection_manager.py	Refactors MSAL connection manager to a thin subclass of the new generic `ConnectionManager`.
libraries/microsoft-agents-authentication-entra-auth-sidecar/setup.py	Packaging entrypoint for the new sidecar auth library (version + deps).
libraries/microsoft-agents-authentication-entra-auth-sidecar/readme.md	Library README with mapping/config/caching documentation.
libraries/microsoft-agents-authentication-entra-auth-sidecar/pyproject.toml	Project metadata for the new sidecar auth library.
libraries/microsoft-agents-authentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/sidecar_http_client.py	Sidecar HTTP client (SSRF guard, retries, parsing, errors).
libraries/microsoft-agents-authentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/sidecar_auth.py	Token provider implementation + caching layer that calls the sidecar.
libraries/microsoft-agents-authentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/errors/error_resources.py	Error messages/resources and sidecar exception types.
libraries/microsoft-agents-authentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/errors/init.py	Public error exports for the sidecar auth library.
libraries/microsoft-agents-authentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/_token_expiry.py	Token expiry resolver (JWT `exp` or fallback).
libraries/microsoft-agents-authentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/_models.py	Sidecar settings/options/result/problem-details models + coercion usage.
libraries/microsoft-agents-authentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/init.py	Public exports for the sidecar auth library.
libraries/microsoft-agents-authentication-entra-auth-sidecar/MANIFEST.in	Includes VERSION.txt in source distribution.
libraries/microsoft-agents-authentication-entra-auth-sidecar/LICENSE	MIT license file for the new package.
libraries/microsoft-agents-activity/microsoft_agents/activity/config/_coercion.py	Adds shared coercion helpers for env-derived values (bool/int/float).
CLAUDE.md	Updates dev docs and library architecture list to include the new package.
.github/workflows/python-package.yml	Installs the newly produced wheel in CI packaging workflow.

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

…ce configuration binding in tests

Copilot

Pull request overview

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

…ent and SidecarAuth functionality

… update related tests for consistency

Copilot

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 3 comments.

…iguration for anonymous access control; add tests for new behaviors

Copilot

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 2 comments.

rodrigobr-msft · 2026-07-08T20:54:20Z

+        # sidecar) expose it as ``configuration``. The only value needed here is
+        # the optional alternate-blueprint connection name.
+        configuration = getattr(connection, "_msal_configuration", None)
+        if configuration is None:
+            configuration = getattr(connection, "configuration", None)
+
+        alt_blueprint_id = (
+            getattr(configuration, "ALT_BLUEPRINT_ID", None) if configuration else None
+        )


I'm adding a comment here for completion. This not ideal, but this method was like that already, but this is a good reminder that this needs to be cleaned up. I will create a task for it

Copilot

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 2 comments.

Copilot

Pull request overview

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

…support raw mapping input; improve error handling in SidecarHttpClient to redact sensitive information from URLs; add tests for new behaviors in connection management and token expiry handling.

Copilot

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 2 comments.

…sidecar-auth

Copilot

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 3 comments.

Copilot

Pull request overview

Copilot reviewed 40 out of 41 changed files in this pull request and generated 2 comments.

…nents

Copilot

Pull request overview

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

…er retries

Copilot

Pull request overview

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

+def _make_client(handler, **kwargs):
+    transport = httpx.MockTransport(handler)
+    http_client = httpx.AsyncClient(transport=transport)
+    return SidecarHttpClient("http://localhost:5178", http_client=http_client, **kwargs)


Initial version entra auth sidecar

7f24d14

Copilot AI review requested due to automatic review settings June 18, 2026 21:26

matthewmeyer requested a review from a team as a code owner June 18, 2026 21:26

Copilot started reviewing on behalf of matthewmeyer June 18, 2026 21:26 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

web-flow added 2 commits June 18, 2026 15:14

Add installation step for Entra auth sidecar wheel

520f795

Refactor connection manager to handle empty connections map and enhan…

9d9c0b8

…ce configuration binding in tests

Copilot AI review requested due to automatic review settings June 18, 2026 22:25

Copilot started reviewing on behalf of matthewmeyer June 18, 2026 22:25 View session

Copilot AI reviewed Jun 18, 2026

View reviewed changes

Comment thread ...entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/sidecar_http_client.py Outdated

Remove HTTP_CLIENT_NAME constant and add new tests for SidecarHttpCli…

6198198

…ent and SidecarAuth functionality

rodrigobr-msft requested changes Jun 22, 2026

View reviewed changes

Comment thread libraries/microsoft-agents-activity/microsoft_agents/activity/config/_coercion.py Outdated

Comment thread libraries/microsoft-agents-activity/microsoft_agents/activity/config/_coercion.py Outdated

Refactor coerce_bool function to improve handling of unset values and…

307a5a0

… update related tests for consistency

Copilot AI review requested due to automatic review settings June 25, 2026 14:35

Copilot started reviewing on behalf of matthewmeyer June 25, 2026 14:35 View session

Copilot AI reviewed Jun 25, 2026

View reviewed changes

matthewmeyer and others added 2 commits June 29, 2026 07:08

Merge branch 'main' into users/matthewm/entra-sidecar-auth

a71bf8d

Enhance error handling in SidecarHttpClient and improve AgentAuthConf…

d00ae64

…iguration for anonymous access control; add tests for new behaviors

Copilot AI review requested due to automatic review settings June 29, 2026 15:41

Copilot started reviewing on behalf of matthewmeyer June 29, 2026 15:42 View session

Copilot AI reviewed Jun 29, 2026

View reviewed changes

Comment thread ...rosoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/connection_manager.py Outdated

Comment thread ...hentication-entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/_models.py Outdated

rodrigobr-msft requested changes Jul 8, 2026

View reviewed changes

Review feedback

2f0b65b

Copilot AI review requested due to automatic review settings July 9, 2026 21:51

Copilot started reviewing on behalf of matthewmeyer July 9, 2026 21:52 View session

Merge branch 'main' into users/matthewm/entra-sidecar-auth

f479805

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread ...-agents-hosting-core/microsoft_agents/hosting/core/authorization/agent_auth_configuration.py Outdated

Comment thread ...rosoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/connection_manager.py Outdated

Copilot AI review requested due to automatic review settings July 9, 2026 21:56

Copilot started reviewing on behalf of matthewmeyer July 9, 2026 21:57 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Automated reveiw feedback fixes.Enhance SidecarConnectionSettings to …

41aad89

…support raw mapping input; improve error handling in SidecarHttpClient to redact sensitive information from URLs; add tests for new behaviors in connection management and token expiry handling.

Copilot AI review requested due to automatic review settings July 10, 2026 17:17

Copilot started reviewing on behalf of matthewmeyer July 10, 2026 17:18 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread ...entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/sidecar_http_client.py

Comment thread ...rosoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/connection_manager.py Outdated

Merge remote-tracking branch 'origin/main' into users/matthewm/entra-…

7e32156

…sidecar-auth

Copilot AI review requested due to automatic review settings July 10, 2026 19:50

Copilot started reviewing on behalf of matthewmeyer July 10, 2026 19:51 View session

Automated review fixes

f584c57

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 10, 2026 19:55

Copilot started reviewing on behalf of matthewmeyer July 10, 2026 19:55 View session

Copilot AI reviewed Jul 10, 2026

View reviewed changes

Comment thread ...entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/sidecar_http_client.py Outdated

Comment thread ...rosoft-agents-hosting-core/microsoft_agents/hosting/core/authorization/connection_manager.py Outdated

Normalize scope whitespace and enhance URL redaction in Sidecar compo…

af37bff

…nents

Copilot AI review requested due to automatic review settings July 13, 2026 14:44

Copilot started reviewing on behalf of matthewmeyer July 13, 2026 14:47 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Comment thread ...entra-auth-sidecar/microsoft_agents/authentication/entra_auth_sidecar/sidecar_http_client.py

Handle transient status errors by raising SidecarUnavailableError aft…

9d8ead3

…er retries

Copilot AI review requested due to automatic review settings July 13, 2026 16:27

Copilot started reviewing on behalf of matthewmeyer July 13, 2026 16:30 View session

Copilot AI reviewed Jul 13, 2026

View reviewed changes

Uh oh!

Conversation

matthewmeyer commented Jun 18, 2026

New authentication package: Entra Auth Sidecar

Documentation updates

Build and install process

Configuration and utility enhancements

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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rodrigobr-msft Jul 8, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment