nvidia-nat-a2a 1.4.0a20251207__py3-none-any.whl → 1.4.0a20251224__py3-none-any.whl

nat/plugins/a2a/auth/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Authentication support for A2A clients."""

nat/plugins/a2a/auth/credential_service.py

@@ -0,0 +1,418 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Bridge NAT AuthProviderBase to A2A SDK CredentialService."""
+
+import asyncio
+import logging
+
+from a2a.client import ClientCallContext
+from a2a.client import CredentialService
+from a2a.types import AgentCard
+from a2a.types import APIKeySecurityScheme
+from a2a.types import HTTPAuthSecurityScheme
+from a2a.types import OAuth2SecurityScheme
+from a2a.types import OpenIdConnectSecurityScheme
+from a2a.types import SecurityScheme
+from nat.authentication.interfaces import AuthProviderBase
+from nat.builder.context import Context
+from nat.data_models.authentication import AuthResult
+from nat.data_models.authentication import BasicAuthCred
+from nat.data_models.authentication import BearerTokenCred
+from nat.data_models.authentication import CookieCred
+from nat.data_models.authentication import HeaderCred
+from nat.data_models.authentication import QueryCred
+
+logger = logging.getLogger(__name__)
+
+
+class A2ACredentialService(CredentialService):
+    """
+    Adapts NAT AuthProviderBase to A2A SDK CredentialService interface.
+
+    This class bridges NAT's authentication system with the A2A SDK's authentication
+    mechanism, allowing A2A clients to use NAT's auth providers (API Key, OAuth2, etc.)
+    to authenticate with A2A agents.
+
+    The adapter:
+    - Calls NAT auth provider to obtain credentials
+    - Maps NAT credential types to A2A security scheme requirements
+    - Handles token expiration and automatic refresh
+    - Supports session-based multi-user authentication
+
+    Args:
+        auth_provider: NAT authentication provider instance
+        agent_card: Agent card containing security scheme definitions
+    """
+
+    def __init__(
+        self,
+        auth_provider: AuthProviderBase,
+        agent_card: AgentCard | None = None,
+    ):
+        self._auth_provider = auth_provider
+        self._agent_card = agent_card
+        self._cached_auth_result: AuthResult | None = None
+        self._auth_lock = asyncio.Lock()
+
+        # Validate provider compatibility with agent's security requirements
+        self._validate_provider_compatibility()
+
+    async def get_credentials(
+        self,
+        security_scheme_name: str,
+        context: ClientCallContext | None,
+    ) -> str | None:
+        """
+        Retrieve credentials for a security scheme.
+
+        This method:
+        1. Gets user_id from NAT context
+        2. Authenticates via NAT auth provider
+        3. Handles token expiration and refresh
+        4. Maps credentials to the requested security scheme
+
+        Args:
+            security_scheme_name: Name of the security scheme from AgentCard
+            context: Client call context with optional session information
+
+        Returns:
+            Credential string or None if not available
+        """
+        # Get user_id from NAT context
+        user_id = Context.get().user_id
+
+        # Authenticate and get credentials from NAT provider
+        auth_result = await self._authenticate(user_id)
+
+        if not auth_result:
+            logger.warning("Authentication failed, no credentials available")
+            return None
+
+        # Map NAT credentials to A2A format based on security scheme
+        credential = self._extract_credential_for_scheme(auth_result, security_scheme_name)
+
+        if credential:
+            logger.debug(
+                "Successfully retrieved credentials for scheme '%s'",
+                security_scheme_name,
+            )
+        else:
+            logger.warning(
+                "No compatible credentials found for scheme '%s'",
+                security_scheme_name,
+            )
+
+        return credential
+
+    async def _authenticate(self, user_id: str | None) -> AuthResult | None:
+        """
+        Authenticate and get credentials from NAT auth provider.
+
+        Handles token expiration by triggering re-authentication if needed.
+        Uses a lock to prevent concurrent authentication requests and race conditions.
+
+        Args:
+            user_id: User identifier for authentication
+
+        Returns:
+            AuthResult with credentials or None on failure
+        """
+        try:
+            # Fast path: check cache without lock
+            auth_result = self._cached_auth_result
+            if auth_result and not auth_result.is_expired():
+                return auth_result
+
+            # Acquire lock to serialize authentication attempts
+            async with self._auth_lock:
+                # Double-check: another coroutine may have refreshed while we waited for lock
+                auth_result = self._cached_auth_result
+                if auth_result and not auth_result.is_expired():
+                    logger.debug("Credentials were refreshed by another coroutine while waiting for lock")
+                    return auth_result
+
+                # Log if we're refreshing expired credentials
+                if auth_result and auth_result.is_expired():
+                    logger.info("Cached credentials expired, re-authenticating")
+
+                # Call NAT auth provider (provider is responsible for token refresh/validity)
+                auth_result = await self._auth_provider.authenticate(user_id=user_id)
+
+                # Cache the result while holding the lock
+                self._cached_auth_result = auth_result
+
+                # Warn if provider returned expired credentials (provider bug)
+                if auth_result and auth_result.is_expired():
+                    logger.warning("Auth provider returned already-expired credentials. "
+                                   "This may indicate a bug in the auth provider's token refresh logic.")
+
+                return auth_result
+
+        except Exception as e:
+            logger.error("Authentication failed: %s", e, exc_info=True)
+            return None
+
+    def _extract_credential_for_scheme(self, auth_result: AuthResult, security_scheme_name: str) -> str | None:
+        """
+        Extract appropriate credential based on security scheme type.
+
+        Maps NAT credential types to A2A security scheme requirements:
+        - BearerTokenCred -> OAuth2, OIDC, HTTP Bearer
+        - HeaderCred -> API Key in header
+        - QueryCred -> API Key in query
+        - CookieCred -> API Key in cookie
+        - BasicAuthCred -> HTTP Basic
+
+        Args:
+            auth_result: Authentication result containing credentials
+            security_scheme_name: Name of the security scheme
+
+        Returns:
+            Credential string or None
+        """
+        # Get scheme definition from agent card
+        scheme_def = self._get_scheme_definition(security_scheme_name)
+
+        # Try to match NAT credentials to security scheme
+        for cred in auth_result.credentials:
+            # Check compatibility and extract credential value
+            credential_value = None
+
+            if isinstance(cred, BearerTokenCred) and self._is_bearer_compatible(scheme_def):
+                credential_value = cred.token.get_secret_value()
+            elif isinstance(cred, HeaderCred) and self._is_header_compatible(scheme_def, cred.name):
+                credential_value = cred.value.get_secret_value()
+            elif isinstance(cred, QueryCred) and self._is_query_compatible(scheme_def, cred.name):
+                credential_value = cred.value.get_secret_value()
+            elif isinstance(cred, CookieCred) and self._is_cookie_compatible(scheme_def, cred.name):
+                credential_value = cred.value.get_secret_value()
+            elif isinstance(cred, BasicAuthCred) and self._is_basic_compatible(scheme_def):
+                # For HTTP Basic, encode username:password as base64
+                import base64
+
+                username = cred.username.get_secret_value()
+                password = cred.password.get_secret_value()
+                credentials = f"{username}:{password}"
+                credential_value = base64.b64encode(credentials.encode()).decode()
+
+            if credential_value:
+                return credential_value
+
+        return None
+
+    def _get_scheme_definition(self, scheme_name: str) -> SecurityScheme | None:
+        """
+        Get security scheme definition from agent card.
+
+        Args:
+            scheme_name: Name of the security scheme
+
+        Returns:
+            SecurityScheme definition or None
+        """
+        if not self._agent_card or not self._agent_card.security_schemes:
+            return None
+        return self._agent_card.security_schemes.get(scheme_name)
+
+    def _validate_provider_compatibility(self) -> None:
+        """
+        Validate that the auth provider type is compatible with agent's security schemes.
+
+        This performs early validation at connection time to fail fast if there's a
+        configuration mismatch between the NAT auth provider and the A2A agent's
+        security requirements.
+
+        Raises:
+            ValueError: If the provider is incompatible with all required security schemes
+        """
+        if not self._agent_card or not self._agent_card.security_schemes:
+            # No security schemes defined, nothing to validate
+            logger.debug("No security schemes defined in agent card, skipping validation")
+            return
+
+        provider_type = type(self._auth_provider).__name__
+        schemes = self._agent_card.security_schemes
+
+        logger.info("Validating auth provider '%s' against agent security schemes: %s",
+                    provider_type,
+                    list(schemes.keys()))
+
+        # Check if provider type is compatible with at least one security scheme
+        compatible_schemes = []
+        incompatible_schemes = []
+
+        for scheme_name, scheme in schemes.items():
+            is_compatible = self._is_provider_compatible_with_scheme(scheme)
+            if is_compatible:
+                compatible_schemes.append(scheme_name)
+            else:
+                incompatible_schemes.append((scheme_name, type(scheme.root).__name__))
+
+        if not compatible_schemes:
+            # Provider is not compatible with any security scheme
+            scheme_details = ", ".join(f"{name} ({scheme_type})" for name, scheme_type in incompatible_schemes)
+            raise ValueError(f"Auth provider '{provider_type}' is not compatible with agent's "
+                             f"security requirements. Agent requires: {scheme_details}")
+
+        logger.info("Auth provider '%s' is compatible with schemes: %s", provider_type, compatible_schemes)
+
+    def _is_provider_compatible_with_scheme(self, scheme: SecurityScheme) -> bool:
+        """
+        Check if the current auth provider can satisfy a security scheme.
+
+        Args:
+            scheme: Security scheme from agent card
+
+        Returns:
+            True if provider is compatible with the scheme
+        """
+        provider_type = type(self._auth_provider).__name__
+
+        # OAuth2/OIDC schemes require OAuth2 providers
+        if isinstance(scheme.root, OAuth2SecurityScheme | OpenIdConnectSecurityScheme):
+            return "OAuth2" in provider_type
+
+        # API Key schemes (can be in header, query, or cookie)
+        if isinstance(scheme.root, APIKeySecurityScheme):
+            return "APIKey" in provider_type
+
+        # HTTP Auth schemes (Basic or Bearer)
+        if isinstance(scheme.root, HTTPAuthSecurityScheme):
+            scheme_lower = scheme.root.scheme.lower()
+            if scheme_lower == "basic":
+                return "HTTPBasic" in provider_type or "BasicAuth" in provider_type
+            elif scheme_lower == "bearer":
+                # Bearer can be satisfied by OAuth2 or API Key providers
+                return "OAuth2" in provider_type or "APIKey" in provider_type
+
+        # Unknown or unsupported scheme type
+        logger.warning("Unknown security scheme type: %s", type(scheme.root).__name__)
+        return False
+
+    @staticmethod
+    def _is_bearer_compatible(scheme_def: SecurityScheme | None) -> bool:
+        """
+        Check if security scheme accepts Bearer tokens.
+
+        Bearer tokens are compatible with:
+        - OAuth2SecurityScheme
+        - OpenIdConnectSecurityScheme
+        - HTTPAuthSecurityScheme with scheme='bearer'
+
+        Args:
+            scheme_def: Security scheme definition
+
+        Returns:
+            True if Bearer token is compatible
+        """
+        if not scheme_def:
+            return False
+
+        # Check for OAuth2 or OIDC schemes
+        if isinstance(scheme_def.root, OAuth2SecurityScheme | OpenIdConnectSecurityScheme):
+            return True
+
+        # Check for HTTP Bearer scheme
+        if isinstance(scheme_def.root, HTTPAuthSecurityScheme):
+            return scheme_def.root.scheme.lower() == "bearer"
+
+        return False
+
+    @staticmethod
+    def _is_header_compatible(scheme_def: SecurityScheme | None, header_name: str) -> bool:
+        """
+        Check if security scheme accepts header-based API keys.
+
+        Args:
+            scheme_def: Security scheme definition
+            header_name: Name of the header containing the credential
+
+        Returns:
+            True if header credential is compatible
+        """
+        if not scheme_def:
+            return False
+
+        # Check for API Key in header
+        if isinstance(scheme_def.root, APIKeySecurityScheme):
+            if scheme_def.root.in_ == "header":
+                # Match header name (case-insensitive)
+                return scheme_def.root.name.lower() == header_name.lower()
+
+        return False
+
+    @staticmethod
+    def _is_query_compatible(scheme_def: SecurityScheme | None, param_name: str) -> bool:
+        """
+        Check if security scheme accepts query parameter API keys.
+
+        Args:
+            scheme_def: Security scheme definition
+            param_name: Name of the query parameter
+
+        Returns:
+            True if query credential is compatible
+        """
+        if not scheme_def:
+            return False
+
+        # Check for API Key in query
+        if isinstance(scheme_def.root, APIKeySecurityScheme):
+            if scheme_def.root.in_ == "query":
+                return scheme_def.root.name == param_name
+
+        return False
+
+    @staticmethod
+    def _is_cookie_compatible(scheme_def: SecurityScheme | None, cookie_name: str) -> bool:
+        """
+        Check if security scheme accepts cookie-based API keys.
+
+        Args:
+            scheme_def: Security scheme definition
+            cookie_name: Name of the cookie
+
+        Returns:
+            True if cookie credential is compatible
+        """
+        if not scheme_def:
+            return False
+
+        # Check for API Key in cookie
+        if isinstance(scheme_def.root, APIKeySecurityScheme):
+            if scheme_def.root.in_ == "cookie":
+                return scheme_def.root.name == cookie_name
+
+        return False
+
+    @staticmethod
+    def _is_basic_compatible(scheme_def: SecurityScheme | None) -> bool:
+        """
+        Check if security scheme accepts HTTP Basic authentication.
+
+        Args:
+            scheme_def: Security scheme definition
+
+        Returns:
+            True if Basic auth is compatible
+        """
+        if not scheme_def:
+            return False
+
+        # Check for HTTP Basic scheme
+        if isinstance(scheme_def.root, HTTPAuthSecurityScheme):
+            return scheme_def.root.scheme.lower() == "basic"
+
+        return False

nat/plugins/a2a/client/client_base.py

@@ -18,6 +18,7 @@ from __future__ import annotations
 import logging
 from collections.abc import AsyncGenerator
 from datetime import timedelta
+from typing import TYPE_CHECKING
 from uuid import uuid4
 
 import httpx
@@ -34,6 +35,9 @@ from a2a.types import Role
 from a2a.types import Task
 from a2a.types import TextPart
 
+if TYPE_CHECKING:
+    from nat.authentication.interfaces import AuthProviderBase
+
 logger = logging.getLogger(__name__)
 
 
@@ -43,20 +47,25 @@ class A2ABaseClient:
 
     Args:
         base_url: The base URL of the A2A agent
+        agent_card_path: Path to agent card (default: /.well-known/agent-card.json)
         task_timeout: Timeout for task operations (default: 300 seconds)
+        streaming: Enable streaming responses (default: True)
+        auth_provider: Optional NAT authentication provider for securing requests
     """
 
     def __init__(
-            self,
-            base_url: str,
-            agent_card_path: str = "/.well-known/agent-card.json",
-            task_timeout: timedelta = timedelta(seconds=300),
-            streaming: bool = True,
+        self,
+        base_url: str,
+        agent_card_path: str = "/.well-known/agent-card.json",
+        task_timeout: timedelta = timedelta(seconds=300),
+        streaming: bool = True,
+        auth_provider: AuthProviderBase | None = None,
     ):
         self._base_url = base_url
         self._agent_card_path = agent_card_path
         self._task_timeout = task_timeout
         self._streaming = streaming
+        self._auth_provider = auth_provider
 
         self._httpx_client: httpx.AsyncClient | None = None
         self._client: Client | None = None
@@ -82,13 +91,30 @@ class A2ABaseClient:
         if not self._agent_card:
             raise RuntimeError("Agent card not resolved")
 
-        # 3) Create A2A client
+        # 3) Setup authentication interceptors if auth is configured
+        interceptors = []
+        if self._auth_provider:
+            try:
+                from a2a.client import AuthInterceptor
+                from nat.plugins.a2a.auth.credential_service import A2ACredentialService
+
+                credential_service = A2ACredentialService(
+                    auth_provider=self._auth_provider,
+                    agent_card=self._agent_card,
+                )
+                interceptors.append(AuthInterceptor(credential_service))
+                logger.info("Authentication configured for A2A client")
+            except ImportError as e:
+                logger.error("Failed to setup authentication: %s", e)
+                raise RuntimeError("Authentication requires a2a-sdk with AuthInterceptor support") from e
+
+        # 4) Create A2A client with interceptors
         client_config = ClientConfig(
             httpx_client=self._httpx_client,
             streaming=self._streaming,
         )
         factory = ClientFactory(client_config)
-        self._client = factory.create(self._agent_card)
+        self._client = factory.create(self._agent_card, interceptors=interceptors)
 
         logger.info("Connected to A2A agent at %s", self._base_url)
         return self

nat/plugins/a2a/client/client_config.py

@@ -65,5 +65,8 @@ class A2AClientConfig(FunctionGroupBaseConfig, name="a2a_client"):
         description="Whether to enable streaming support for the A2A client",
     )
 
-    auth_provider: str | AuthenticationRef | None = Field(default=None,
-                                                          description="Reference to authentication provider")
+    auth_provider: str | AuthenticationRef | None = Field(
+        default=None,
+        description="Reference to NAT authentication provider for authenticating with the A2A agent. "
+        "Supports OAuth2, API Key, HTTP Basic, and other NAT auth providers.",
+    )

nat/plugins/a2a/client/client_impl.py

@@ -15,6 +15,7 @@
 
 import logging
 from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING
 from typing import Any
 
 from pydantic import BaseModel
@@ -22,10 +23,13 @@ from pydantic import Field
 
 from nat.builder.function import FunctionGroup
 from nat.builder.workflow_builder import Builder
-from nat.cli.register_workflow import register_function_group
+from nat.cli.register_workflow import register_per_user_function_group
 from nat.plugins.a2a.client.client_base import A2ABaseClient
 from nat.plugins.a2a.client.client_config import A2AClientConfig
 
+if TYPE_CHECKING:
+    from nat.authentication.interfaces import AuthProviderBase
+
 logger = logging.getLogger(__name__)
 
 
@@ -66,13 +70,36 @@ class A2AClientFunctionGroup(FunctionGroup):
         config: A2AClientConfig = self._config  # type: ignore[assignment]
         base_url = str(config.url)
 
+        # Get user_id from context (set by runtime for per-user function groups)
+        from nat.builder.context import Context
+        user_id = Context.get().user_id
+        if not user_id:
+            raise RuntimeError("User ID not found in context")
+
+        # Resolve auth provider if configured
+        auth_provider: AuthProviderBase | None = None
+        if config.auth_provider:
+            try:
+                auth_provider = await self._builder.get_auth_provider(config.auth_provider)
+                logger.info("Resolved authentication provider for A2A client")
+            except Exception as e:
+                logger.error("Failed to resolve auth provider '%s': %s", config.auth_provider, e)
+                raise RuntimeError(f"Failed to resolve auth provider: {e}") from e
+
         # Create and initialize A2A client
-        self._client = A2ABaseClient(base_url=base_url,
-                                     agent_card_path=config.agent_card_path,
-                                     task_timeout=config.task_timeout,
-                                     streaming=config.streaming)
+        self._client = A2ABaseClient(
+            base_url=base_url,
+            agent_card_path=config.agent_card_path,
+            task_timeout=config.task_timeout,
+            streaming=config.streaming,
+            auth_provider=auth_provider,
+        )
         await self._client.__aenter__()
-        logger.info("Connected to A2A agent at %s", base_url)
+
+        if auth_provider:
+            logger.info("Connected to A2A agent at %s with authentication (user_id: %s)", base_url, user_id)
+        else:
+            logger.info("Connected to A2A agent at %s (user_id: %s)", base_url, user_id)
 
         # Discover agent card and register functions
         self._register_functions()
@@ -281,11 +308,12 @@ class A2AClientFunctionGroup(FunctionGroup):
             yield event
 
 
-@register_function_group(config_type=A2AClientConfig)
+@register_per_user_function_group(config_type=A2AClientConfig)
 async def a2a_client_function_group(config: A2AClientConfig, _builder: Builder):
     """
     Connect to an A2A agent, discover agent card and publish the primary
-    agent function and helper functions.
+    agent function and helper functions. This function group is per-user,
+    meaning each user gets their own isolated instance.
 
     This function group creates a three-level API:
     - High-level: Agent function named after the agent (e.g., dice_agent)

nat/plugins/a2a/server/front_end_config.py

@@ -17,7 +17,9 @@ import logging
 
 from pydantic import BaseModel
 from pydantic import Field
+from pydantic import model_validator
 
+from nat.authentication.oauth2.oauth2_resource_server_config import OAuth2ResourceServerConfig
 from nat.data_models.front_end import FrontEndBaseConfig
 
 logger = logging.getLogger(__name__)
@@ -102,3 +104,28 @@ class A2AFrontEndConfig(FrontEndBaseConfig, name="a2a"):
         default=None,
         description="Custom worker class for handling A2A routes (default: built-in worker)",
     )
+
+    # OAuth2 Resource Server (for protecting this A2A agent)
+    server_auth: OAuth2ResourceServerConfig | None = Field(
+        default=None,
+        description=("OAuth 2.0 Resource Server configuration for token verification. "
+                     "When configured, the A2A server will validate OAuth2 Bearer tokens on all requests "
+                     "except public agent card discovery. Supports both JWT validation (via JWKS) and "
+                     "opaque token validation (via RFC 7662 introspection)."),
+    )
+
+    @model_validator(mode="after")
+    def validate_security_configuration(self):
+        """Validate security configuration to prevent accidental misconfigurations."""
+        # Check if server is bound to a non-localhost interface without authentication
+        localhost_hosts = {"localhost", "127.0.0.1", "::1"}
+        if self.host not in localhost_hosts and self.server_auth is None:
+            logger.warning(
+                "A2A server is configured to bind to '%s' without authentication. "
+                "This may expose your server to unauthorized access. "
+                "Consider either: (1) binding to localhost for local-only access, "
+                "or (2) configuring server_auth for production deployments on public interfaces.",
+                self.host,
+            )
+
+        return self

nat/plugins/a2a/server/front_end_plugin.py

@@ -53,7 +53,7 @@ class A2AFrontEndPlugin(FrontEndBase[A2AFrontEndConfig]):
             agent_card = await worker.create_agent_card(workflow)
 
             # Create agent executor adapter
-            agent_executor = worker.create_agent_executor(workflow)
+            agent_executor = worker.create_agent_executor(workflow, builder)
 
             # Create A2A server
             a2a_server = worker.create_a2a_server(agent_card, agent_executor)
@@ -70,8 +70,21 @@ class A2AFrontEndPlugin(FrontEndBase[A2AFrontEndConfig]):
                             self.front_end_config.host,
                             self.front_end_config.port)
 
-                # Build the ASGI app and run with uvicorn
+                # Build the ASGI app
                 app = a2a_server.build()
+
+                # Add OAuth2 validation middleware if configured
+                if self.front_end_config.server_auth:
+                    from nat.plugins.a2a.server.oauth_middleware import OAuth2ValidationMiddleware
+
+                    app.add_middleware(OAuth2ValidationMiddleware, config=self.front_end_config.server_auth)
+                    logger.info(
+                        "OAuth2 token validation enabled for A2A server (issuer=%s, scopes=%s)",
+                        self.front_end_config.server_auth.issuer_url,
+                        self.front_end_config.server_auth.scopes,
+                    )
+
+                # Run with uvicorn
                 config = uvicorn.Config(
                     app,
                     host=self.front_end_config.host,

nat/plugins/a2a/server/front_end_plugin_worker.py

@@ -25,8 +25,10 @@ from a2a.server.tasks import InMemoryTaskStore
 from a2a.types import AgentCapabilities
 from a2a.types import AgentCard
 from a2a.types import AgentSkill
+from a2a.types import SecurityScheme
 from nat.builder.function import Function
 from nat.builder.workflow import Workflow
+from nat.builder.workflow_builder import WorkflowBuilder
 from nat.data_models.config import Config
 from nat.plugins.a2a.server.agent_executor_adapter import NATWorkflowAgentExecutor
 from nat.plugins.a2a.server.front_end_config import A2AFrontEndConfig
@@ -72,6 +74,81 @@ class A2AFrontEndPluginWorker:
 
         return functions
 
+    async def _generate_security_schemes(
+            self, server_auth_config) -> tuple[dict[str, SecurityScheme], list[dict[str, list[str]]]]:
+        """Generate A2A security schemes from OAuth2ResourceServerConfig.
+
+        Args:
+            server_auth_config: OAuth2ResourceServerConfig
+
+        Returns:
+            Tuple of (security_schemes dict, security requirements list)
+        """
+        from a2a.types import AuthorizationCodeOAuthFlow
+        from a2a.types import OAuth2SecurityScheme
+        from a2a.types import OAuthFlows
+
+        # Resolve OAuth2 endpoints from configuration
+        auth_url, token_url = await self._resolve_oauth_endpoints(server_auth_config)
+
+        # Create scope descriptions
+        scope_descriptions = {scope: f"Permission: {scope}" for scope in server_auth_config.scopes}
+
+        # Build OAuth2 security scheme
+        security_schemes = {
+            "oauth2":
+                SecurityScheme(root=OAuth2SecurityScheme(
+                    type="oauth2",
+                    description="OAuth 2.0 authentication required to access this agent",
+                    flows=OAuthFlows(authorizationCode=AuthorizationCodeOAuthFlow(
+                        authorizationUrl=auth_url,
+                        tokenUrl=token_url,
+                        scopes=scope_descriptions,
+                    )),
+                ))
+        }
+
+        # Security requirements (scopes needed)
+        security = [{"oauth2": server_auth_config.scopes}]
+
+        return security_schemes, security
+
+    async def _resolve_oauth_endpoints(self, server_auth_config) -> tuple[str, str]:
+        """Resolve authorization and token URLs from OAuth2 configuration.
+
+        Args:
+            server_auth_config: OAuth2ResourceServerConfig
+
+        Returns:
+            Tuple of (authorization_url, token_url)
+        """
+        import httpx
+
+        # If discovery URL is provided, use OIDC discovery
+        if server_auth_config.discovery_url:
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(server_auth_config.discovery_url, timeout=5.0)
+                    response.raise_for_status()
+                    metadata = response.json()
+
+                    auth_url = metadata.get("authorization_endpoint")
+                    token_url = metadata.get("token_endpoint")
+
+                    if auth_url and token_url:
+                        logger.info("Resolved OAuth endpoints via discovery: %s", server_auth_config.discovery_url)
+                        return auth_url, token_url
+            except Exception as e:
+                logger.warning("Failed to discover OAuth endpoints: %s", e)
+
+        # Fallback: derive from issuer URL (common convention)
+        issuer = server_auth_config.issuer_url.rstrip("/")
+        auth_url = f"{issuer}/oauth/authorize"
+        token_url = f"{issuer}/oauth/token"
+
+        logger.info("Using derived OAuth endpoints from issuer: %s", issuer)
+        return auth_url, token_url
+
     async def create_agent_card(self, workflow: Workflow) -> AgentCard:
         """Build AgentCard from configuration and workflow functions.
 
@@ -112,6 +189,18 @@ class A2AFrontEndPluginWorker:
 
         logger.info("Auto-generated %d skills from workflow functions", len(skills))
 
+        # Generate security schemes if server_auth is configured
+        security_schemes = None
+        security = None
+
+        if config.server_auth:
+            security_schemes, security = await self._generate_security_schemes(config.server_auth)
+            logger.info(
+                "Generated OAuth2 security schemes for agent (issuer=%s, scopes=%s)",
+                config.server_auth.issuer_url,
+                config.server_auth.scopes,
+            )
+
         # Build agent card
         agent_url = f"http://{config.host}:{config.port}/"
         agent_card = AgentCard(
@@ -123,15 +212,19 @@ class A2AFrontEndPluginWorker:
             default_output_modes=config.default_output_modes,
             capabilities=capabilities,
             skills=skills,
+            security_schemes=security_schemes,
+            security=security,
         )
 
         logger.info("Created AgentCard for: %s v%s", config.name, config.version)
         logger.info("Agent URL: %s", agent_url)
         logger.info("Skills: %d", len(skills))
+        if security_schemes:
+            logger.info("Security: OAuth2 authentication required")
 
         return agent_card
 
-    def create_agent_executor(self, workflow: Workflow) -> NATWorkflowAgentExecutor:
+    def create_agent_executor(self, workflow: Workflow, builder: WorkflowBuilder) -> NATWorkflowAgentExecutor:
         """Create agent executor adapter for the workflow.
 
         This creates a SessionManager to handle concurrent A2A task requests,
@@ -139,13 +232,16 @@ class A2AFrontEndPluginWorker:
 
         Args:
             workflow: The NAT workflow to expose
+            builder: The workflow builder used to create the workflow
 
         Returns:
             NATWorkflowAgentExecutor that wraps the workflow with a SessionManager
         """
         # Create SessionManager to handle concurrent requests with proper limits
         session_manager = SessionManager(
-            workflow=workflow,
+            config=self.full_config,
+            shared_builder=builder,
+            shared_workflow=workflow,
             max_concurrency=self.max_concurrency,
         )
 

nat/plugins/a2a/server/oauth_middleware.py

@@ -0,0 +1,121 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""OAuth 2.0 token validation middleware for A2A servers."""
+
+import logging
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from nat.authentication.credential_validator.bearer_token_validator import BearerTokenValidator
+from nat.authentication.oauth2.oauth2_resource_server_config import OAuth2ResourceServerConfig
+
+logger = logging.getLogger(__name__)
+
+
+class OAuth2ValidationMiddleware(BaseHTTPMiddleware):
+    """OAuth2 Bearer token validation middleware for A2A servers.
+
+    Validates Bearer tokens using NAT's BearerTokenValidator which supports:
+    - JWT validation via JWKS (RFC 7519)
+    - Opaque token validation via introspection (RFC 7662)
+    - OIDC discovery
+    - Scope and audience enforcement
+
+    The middleware allows public access to the agent card discovery endpoint
+    (/.well-known/agent.json) and validates all other A2A requests.
+    """
+
+    def __init__(self, app, config: OAuth2ResourceServerConfig):
+        """Initialize OAuth2 validation middleware.
+
+        Args:
+            app: Starlette application
+            config: OAuth2 resource server configuration
+        """
+        super().__init__(app)
+
+        # Create validator using NAT's BearerTokenValidator
+        self.validator = BearerTokenValidator(
+            issuer=config.issuer_url,
+            audience=config.audience,
+            scopes=config.scopes,
+            jwks_uri=config.jwks_uri,
+            introspection_endpoint=config.introspection_endpoint,
+            discovery_url=config.discovery_url,
+            client_id=config.client_id,
+            client_secret=config.client_secret.get_secret_value() if config.client_secret else None,
+        )
+
+        logger.info(
+            "OAuth2 validation middleware initialized (issuer=%s, scopes=%s, audience=%s)",
+            config.issuer_url,
+            config.scopes,
+            config.audience,
+        )
+
+    async def dispatch(self, request: Request, call_next):
+        """Validate OAuth2 Bearer token for all requests except agent card discovery.
+
+        Args:
+            request: Incoming HTTP request
+            call_next: Next middleware/handler in chain
+
+        Returns:
+            HTTP response (either error or result from next handler)
+        """
+        # Public: Agent card discovery (per A2A spec)
+        if request.url.path == "/.well-known/agent-card.json":
+            logger.debug("Public access to agent card discovery")
+            return await call_next(request)
+
+        # Extract Bearer token
+        auth_header = request.headers.get("Authorization", "")
+        if not auth_header.startswith("Bearer "):
+            logger.warning("Missing or invalid Authorization header")
+            return JSONResponse({
+                "error": "unauthorized", "message": "Missing or invalid Bearer token"
+            },
+                                status_code=401)
+
+        token = auth_header[7:]  # Strip "Bearer "
+
+        # Validate token using NAT's validator
+        try:
+            result = await self.validator.verify(token)
+        except Exception as e:
+            logger.error(f"Token validation error: {e}")
+            return JSONResponse({"error": "invalid_token", "message": "Token validation failed"}, status_code=403)
+
+        # Check if token is active
+        if not result.active:
+            logger.warning("Token is not active")
+            return JSONResponse({"error": "invalid_token", "message": "Token is not active"}, status_code=403)
+
+        # Attach token info to request state for potential use by handlers
+        request.state.oauth_user = result.subject
+        request.state.oauth_scopes = result.scopes or []
+        request.state.oauth_client_id = result.client_id
+        request.state.oauth_token_info = result
+
+        logger.debug(
+            "Token validated successfully (user=%s, scopes=%s, client=%s)",
+            result.subject,
+            result.scopes,
+            result.client_id,
+        )
+
+        return await call_next(request)

{nvidia_nat_a2a-1.4.0a20251207.dist-info → nvidia_nat_a2a-1.4.0a20251224.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-nat-a2a
-Version: 1.4.0a20251207
+Version: 1.4.0a20251224
 Summary: Subpackage for A2A Protocol integration in NeMo Agent Toolkit
 Author: NVIDIA Corporation
 Maintainer: NVIDIA Corporation
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.14,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: nvidia-nat==v1.4.0a20251207
+Requires-Dist: nvidia-nat==v1.4.0a20251224
 Requires-Dist: a2a-sdk~=0.3.20
 Dynamic: license-file
 

nvidia_nat_a2a-1.4.0a20251224.dist-info/RECORD

@@ -0,0 +1,22 @@
+nat/meta/pypi.md,sha256=YkfjzZntzheoaBie5ZovnAwB78xxVqk9sblkZRZcdLU,1661
+nat/plugins/a2a/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv-tZzbU9W-izgx9aMEQg,680
+nat/plugins/a2a/register.py,sha256=pUN1hbJ38M8GbdNcA0qQzJ1S-ZC91GnRGk_8SO_kTVg,853
+nat/plugins/a2a/auth/__init__.py,sha256=iQFx1YrjFcepS7k8jp93A0IVOkFeNx_I35M6dIngoJA,726
+nat/plugins/a2a/auth/credential_service.py,sha256=-_VdDF4YESaAtY1ONUiOL5z4aGDJZYVuhyhI9BZhuyI,15967
+nat/plugins/a2a/client/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv-tZzbU9W-izgx9aMEQg,680
+nat/plugins/a2a/client/client_base.py,sha256=xShDZDFKa4R2XsY3yBMvM-eDaf_0cdE48XJzQ4WcEOw,13366
+nat/plugins/a2a/client/client_config.py,sha256=KwWjymDg9GUfSYcIaBhcxph4Hu6IeTe414hrNUUo-6g,2875
+nat/plugins/a2a/client/client_impl.py,sha256=CGAjiHr6EyWcnlSipmT8ixgjD4s8VbPRBPOZy2q_Sm0,12958
+nat/plugins/a2a/server/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv-tZzbU9W-izgx9aMEQg,680
+nat/plugins/a2a/server/agent_executor_adapter.py,sha256=wvGXOb3FcV0_pYRv-yr-QzozjzXM909D49Dxm9199xI,7015
+nat/plugins/a2a/server/front_end_config.py,sha256=Lg-qjDmC4fwrwnHNtSRl54pMpdwVnO06xhgbLt-aEZY,4902
+nat/plugins/a2a/server/front_end_plugin.py,sha256=fX3Lagkd48snSiNo2IMTRpR-40WHUWQidpjKu8uQChY,4896
+nat/plugins/a2a/server/front_end_plugin_worker.py,sha256=Ehdv6lyUcrWkfMq7YomD4NYFAusrtQ2JYj2HnkIqGhY,11696
+nat/plugins/a2a/server/oauth_middleware.py,sha256=NvvIJSPB8wRui2eQlxr6AaNhN0JxdUQ1Ajr8Dnk0rnY,4751
+nat/plugins/a2a/server/register_frontend.py,sha256=4TmpBcZF4x71c2xnWuketsygqHmU7D2hKA2bzO34TpU,1480
+nvidia_nat_a2a-1.4.0a20251224.dist-info/licenses/LICENSE.md,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
+nvidia_nat_a2a-1.4.0a20251224.dist-info/METADATA,sha256=7KIbUZYZ3X7iQhe1bvuUrLvSyQndAHLAXxmVxtzrSms,2438
+nvidia_nat_a2a-1.4.0a20251224.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nvidia_nat_a2a-1.4.0a20251224.dist-info/entry_points.txt,sha256=Lacvy6nXpDTv8dh8vKJ_QE8TobliVdhgABuw25t8fBg,145
+nvidia_nat_a2a-1.4.0a20251224.dist-info/top_level.txt,sha256=8-CJ2cP6-f0ZReXe5Hzqp-5pvzzHz-5Ds5H2bGqh1-U,4
+nvidia_nat_a2a-1.4.0a20251224.dist-info/RECORD,,

nvidia_nat_a2a-1.4.0a20251207.dist-info/RECORD

@@ -1,19 +0,0 @@
-nat/meta/pypi.md,sha256=YkfjzZntzheoaBie5ZovnAwB78xxVqk9sblkZRZcdLU,1661
-nat/plugins/a2a/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv-tZzbU9W-izgx9aMEQg,680
-nat/plugins/a2a/register.py,sha256=pUN1hbJ38M8GbdNcA0qQzJ1S-ZC91GnRGk_8SO_kTVg,853
-nat/plugins/a2a/client/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv-tZzbU9W-izgx9aMEQg,680
-nat/plugins/a2a/client/client_base.py,sha256=s0HTS0ebuwoc_fL4Z_laRe-OIZ5iooSG_FzcgZca8_E,12070
-nat/plugins/a2a/client/client_config.py,sha256=SWu46fAa25IYc3Lhq9w9nIt5xkCtdBuuPy74pd5vPPk,2788
-nat/plugins/a2a/client/client_impl.py,sha256=cc_rYyPq86_8R12MjesMHaZrYG9lDnip2125veQ1fEY,11775
-nat/plugins/a2a/server/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv-tZzbU9W-izgx9aMEQg,680
-nat/plugins/a2a/server/agent_executor_adapter.py,sha256=wvGXOb3FcV0_pYRv-yr-QzozjzXM909D49Dxm9199xI,7015
-nat/plugins/a2a/server/front_end_config.py,sha256=Qnjbx6n67Xy3sZ6rkAYZaKk-WfBDrVX5OzZSWxU6fIg,3423
-nat/plugins/a2a/server/front_end_plugin.py,sha256=euhh5LXkZpyC5HaUaJKFJH3BIF6jS2ti3NNXVQ71bgI,4255
-nat/plugins/a2a/server/front_end_plugin_worker.py,sha256=Ih00L9DtZZYQvN_RRw4a5M_StTFhZ4JGHNniw6glOzY,7757
-nat/plugins/a2a/server/register_frontend.py,sha256=4TmpBcZF4x71c2xnWuketsygqHmU7D2hKA2bzO34TpU,1480
-nvidia_nat_a2a-1.4.0a20251207.dist-info/licenses/LICENSE.md,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
-nvidia_nat_a2a-1.4.0a20251207.dist-info/METADATA,sha256=6qhxCj7OS1n7csjZtbbByAd86SYtWVoydK0nFnvDfRc,2438
-nvidia_nat_a2a-1.4.0a20251207.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-nvidia_nat_a2a-1.4.0a20251207.dist-info/entry_points.txt,sha256=Lacvy6nXpDTv8dh8vKJ_QE8TobliVdhgABuw25t8fBg,145
-nvidia_nat_a2a-1.4.0a20251207.dist-info/top_level.txt,sha256=8-CJ2cP6-f0ZReXe5Hzqp-5pvzzHz-5Ds5H2bGqh1-U,4
-nvidia_nat_a2a-1.4.0a20251207.dist-info/RECORD,,