chore: Add a base credential refresher interface

PiperOrigin-RevId: 771625930

Author: seanzhougoogle

src/google/adk/agents/invocation_context.py

@@ -22,6 +22,7 @@
 from pydantic import ConfigDict
 
 from ..artifacts.base_artifact_service import BaseArtifactService
+from ..auth.credential_service.base_credential_service import BaseCredentialService
 from ..memory.base_memory_service import BaseMemoryService
 from ..sessions.base_session_service import BaseSessionService
 from ..sessions.session import Session
@@ -115,6 +116,7 @@ class InvocationContext(BaseModel):
   artifact_service: Optional[BaseArtifactService] = None
   session_service: BaseSessionService
   memory_service: Optional[BaseMemoryService] = None
+  credential_service: Optional[BaseCredentialService] = None
 
   invocation_id: str
   """The id of this invocation context. Readonly."""

src/google/adk/auth/credential_service/base_credential_service.py

@@ -19,12 +19,12 @@
 from typing import Optional
 
 from ...tools.tool_context import ToolContext
-from ...utils.feature_decorator import working_in_progress
+from ...utils.feature_decorator import experimental
 from ..auth_credential import AuthCredential
 from ..auth_tool import AuthConfig
 
 
-@working_in_progress("Implementation are in progress. Don't use it for now.")
+@experimental
 class BaseCredentialService(ABC):
   """Abstract class for Service that loads / saves tool credentials from / to
   the backend credential store."""

src/google/adk/auth/credential_service/in_memory_credential_service.py

@@ -0,0 +1,93 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+from __future__ import annotations
+
+from typing import Optional
+
+from typing_extensions import override
+
+from ...tools.tool_context import ToolContext
+from ...utils.feature_decorator import experimental
+from ..auth_credential import AuthCredential
+from ..auth_tool import AuthConfig
+from .base_credential_service import BaseCredentialService
+
+
+@experimental
+class InMemoryCredentialService(BaseCredentialService):
+  """Class for in memory implementation of credential service(Experimental)"""
+
+  def __init__(self):
+    super().__init__()
+    self._store: dict[str, AuthCredential] = {}
+
+  @override
+  async def load_credential(
+      self,
+      auth_config: AuthConfig,
+      tool_context: ToolContext,
+  ) -> Optional[AuthCredential]:
+    """
+    Loads the credential by auth config and current tool context from the
+    backend credential store.
+
+    Args:
+        auth_config: The auth config which contains the auth scheme and auth
+        credential information. auth_config.get_credential_key will be used to
+        build the key to load the credential.
+
+        tool_context: The context of the current invocation when the tool is
+        trying to load the credential.
+
+    Returns:
+        Optional[AuthCredential]: the credential saved in the store.
+
+    """
+    storage = self._get_storage_for_current_context(tool_context)
+    return storage.get(auth_config.credential_key)
+
+  @override
+  async def save_credential(
+      self,
+      auth_config: AuthConfig,
+      tool_context: ToolContext,
+  ) -> None:
+    """
+    Saves the exchanged_auth_credential in auth config to the backend credential
+    store.
+
+    Args:
+        auth_config: The auth config which contains the auth scheme and auth
+        credential information. auth_config.get_credential_key will be used to
+        build the key to save the credential.
+
+        tool_context: The context of the current invocation when the tool is
+        trying to save the credential.
+
+    Returns:
+        None
+    """
+    storage = self._get_storage_for_current_context(tool_context)
+    storage[auth_config.credential_key] = auth_config.exchanged_auth_credential
+
+  def _get_storage_for_current_context(self, tool_context: ToolContext) -> str:
+    app_name = tool_context._invocation_context.app_name
+    user_id = tool_context._invocation_context.user_id
+
+    if app_name not in self._store:
+      self._store[app_name] = {}
+    if user_id not in self._store[app_name]:
+      self._store[app_name][user_id] = {}
+    return self._store[app_name][user_id]

src/google/adk/auth/exchanger/__init__.py

@@ -0,0 +1,23 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+"""Credential exchanger module."""
+
+from .base_credential_exchanger import BaseCredentialExchanger
+from .service_account_credential_exchanger import ServiceAccountCredentialExchanger
+
+__all__ = [
+    "BaseCredentialExchanger",
+    "ServiceAccountCredentialExchanger",
+]

src/google/adk/auth/exchanger/base_credential_exchanger.py

@@ -0,0 +1,49 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+"""Base credential exchanger interface."""
+
+from __future__ import annotations
+
+import abc
+from typing import Optional
+
+from ...utils.feature_decorator import experimental
+from ..auth_credential import AuthCredential
+from ..auth_schemes import AuthScheme
+
+
+@experimental
+class BaseCredentialExchanger(abc.ABC):
+  """Base interface for credential exchangers."""
+
+  @abc.abstractmethod
+  def exchange(
+      self,
+      auth_credential: AuthCredential,
+      auth_scheme: Optional[AuthScheme] = None,
+  ) -> AuthCredential:
+    """Exchange credential if needed.
+
+    Args:
+        auth_credential: The credential to exchange.
+        auth_scheme: The authentication scheme (optional, some exchangers don't need it).
+
+    Returns:
+        The exchanged credential.
+
+    Raises:
+        ValueError: If credential exchange fails.
+    """
+    pass

src/google/adk/auth/exchanger/credential_exchanger_registry.py

@@ -0,0 +1,58 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+"""Credential exchanger registry."""
+
+from __future__ import annotations
+
+from typing import Dict
+from typing import Optional
+
+from ...utils.feature_decorator import experimental
+from ..auth_credential import AuthCredentialTypes
+from .base_credential_exchanger import BaseCredentialExchanger
+
+
+@experimental
+class CredentialExchangerRegistry:
+  """Registry for credential exchanger instances."""
+
+  def __init__(self):
+    self._exchangers: Dict[AuthCredentialTypes, BaseCredentialExchanger] = {}
+
+  def register(
+      self,
+      credential_type: AuthCredentialTypes,
+      exchanger_instance: BaseCredentialExchanger,
+  ) -> None:
+    """Register an exchanger instance for a credential type.
+
+    Args:
+        credential_type: The credential type to register for.
+        exchanger_instance: The exchanger instance to register.
+    """
+    self._exchangers[credential_type] = exchanger_instance
+
+  def get_exchanger(
+      self, credential_type: AuthCredentialTypes
+  ) -> Optional[BaseCredentialExchanger]:
+    """Get the exchanger instance for a credential type.
+
+    Args:
+        credential_type: The credential type to get exchanger for.
+
+    Returns:
+        The exchanger instance if registered, None otherwise.
+    """
+    return self._exchangers.get(credential_type)

src/google/adk/auth/service_account_credential_exchanger.py renamed to src/google/adk/auth/exchanger/service_account_credential_exchanger.py

@@ -16,64 +16,82 @@
 
 from __future__ import annotations
 
+from typing import Optional
+
 import google.auth
 from google.auth.transport.requests import Request
 from google.oauth2 import service_account
 
-from ..utils.feature_decorator import experimental
-from .auth_credential import AuthCredential
-from .auth_credential import AuthCredentialTypes
-from .auth_credential import HttpAuth
-from .auth_credential import HttpCredentials
+from ...utils.feature_decorator import experimental
+from ..auth_credential import AuthCredential
+from ..auth_credential import AuthCredentialTypes
+from ..auth_credential import ServiceAccount
+from ..auth_schemes import AuthScheme
+from .base_credential_exchanger import BaseCredentialExchanger
 
 
 @experimental
-class ServiceAccountCredentialExchanger:
+class ServiceAccountCredentialExchanger(BaseCredentialExchanger):
   """Exchanges Google Service Account credentials for an access token.
 
   Uses the default service credential if `use_default_credential = True`.
   Otherwise, uses the service account credential provided in the auth
   credential.
   """
 
-  def __init__(self, credential: AuthCredential):
-    if credential.auth_type != AuthCredentialTypes.SERVICE_ACCOUNT:
-      raise ValueError("Credential is not a service account credential.")
-    self._credential = credential
+  def __init__(self):
+    """Initialize the service account credential exchanger."""
+    pass
 
-  def exchange(self) -> AuthCredential:
+  def exchange(
+      self,
+      auth_credential: AuthCredential,
+      auth_scheme: Optional[AuthScheme] = None,
+  ) -> AuthCredential:
     """Exchanges the service account auth credential for an access token.
 
     If the AuthCredential contains a service account credential, it will be used
     to exchange for an access token. Otherwise, if use_default_credential is True,
     the default application credential will be used for exchanging an access token.
 
+    Args:
+        auth_scheme: The authentication scheme.
+        auth_credential: The credential to exchange.
+
     Returns:
-        An AuthCredential in HTTP Bearer format, containing the access token.
+        An AuthCredential in OAUTH2 format, containing the exchanged credential JSON.
 
     Raises:
         ValueError: If service account credentials are missing or invalid.
         Exception: If credential exchange or refresh fails.
     """
+    if auth_credential is None:
+      raise ValueError("Credential cannot be None.")
+
+    if auth_credential.auth_type != AuthCredentialTypes.SERVICE_ACCOUNT:
+      raise ValueError("Credential is not a service account credential.")
+
+    if auth_credential.service_account is None:
+      raise ValueError(
+          "Service account credentials are missing. Please provide them."
+      )
+
     if (
-        self._credential is None
-        or self._credential.service_account is None
-        or (
-            self._credential.service_account.service_account_credential is None
-            and not self._credential.service_account.use_default_credential
-        )
+        auth_credential.service_account.service_account_credential is None
+        and not auth_credential.service_account.use_default_credential
     ):
       raise ValueError(
-          "Service account credentials are missing. Please provide them, or set"
-          " `use_default_credential = True` to use application default"
-          " credential in a hosted service like Google Cloud Run."
+          "Service account credentials are invalid. Please set the"
+          " service_account_credential field or set `use_default_credential ="
+          " True` to use application default credential in a hosted service"
+          " like Google Cloud Run."
       )
 
     try:
-      if self._credential.service_account.use_default_credential:
+      if auth_credential.service_account.use_default_credential:
         credentials, _ = google.auth.default()
       else:
-        config = self._credential.service_account
+        config = auth_credential.service_account
         credentials = service_account.Credentials.from_service_account_info(
             config.service_account_credential.model_dump(), scopes=config.scopes
         )
@@ -82,11 +100,8 @@ def exchange(self) -> AuthCredential:
       credentials.refresh(Request())
 
       return AuthCredential(
-          auth_type=AuthCredentialTypes.HTTP,
-          http=HttpAuth(
-              scheme="bearer",
-              credentials=HttpCredentials(token=credentials.token),
-          ),
+          auth_type=AuthCredentialTypes.OAUTH2,
+          google_oauth2_json=credentials.to_json(),
       )
     except Exception as e:
       raise ValueError(f"Failed to exchange service account token: {e}") from e

src/google/adk/auth/refresher/__init__.py

@@ -0,0 +1,21 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+"""Credential refresher module."""
+
+from .base_credential_refresher import BaseCredentialRefresher
+
+__all__ = [
+    "BaseCredentialRefresher",
+]