From 99cf002538e9d616f80519f68391fcd56905491e Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Wed, 8 Apr 2026 23:57:14 +0000 Subject: [PATCH 1/2] docs: update tools auth with additional recommendations - auth manager services - self-managed auth --- docs/tools-custom/authentication.md | 49 +++++++++++++++++++++++------ 1 file changed, 39 insertions(+), 10 deletions(-) diff --git a/docs/tools-custom/authentication.md b/docs/tools-custom/authentication.md index 7a33b3904..e08666eba 100644 --- a/docs/tools-custom/authentication.md +++ b/docs/tools-custom/authentication.md @@ -28,16 +28,45 @@ There are several ways to manage authentication and credentials in ADK agents. Each of these methods carries some amount of risk, so you should carefully consider which approach best serves your application and customers. -### Recommended: Secrets manager services - -For production environments, storing sensitive credentials in a dedicated secret -manager is the **most recommended approach**. With this approach, the secret -manager securely stores the credentials for any tools or services accessed by -the agent as needed, and those secrets are not resident in agent's operating -memory. For example, a custom ADK Tool using this method would store only -short-lived access tokens or secure references, and retrieve longer-lived -refresh tokens from the secrets manager when needed. When selecting a secrets -manager service, consider services from well-established providers, such as +### Recommended: Authentication manager services + +When deploying agents to production hosted environments, your agent's ability to +properly authenticate to restricted tools and services becomes more challenging +and more important to properly manage. This authentication challenge can become +even more complicated when users of your agent have varying levels of access to +restricted tools and data. Rather than writing code to handle the authentication +process and credential managment for various tools used by your agent, use an +*authentication manager* service that manages *both* for you. This service +should handle the storage of keys and secrets, as well as the acquisition, +management, and storage of OAuth access or refresh tokens. + +### Self-managed authentication + +If you decide to manage your own authentication process with ADK helper functions +and your own code, consider these recommendations: + +* **API keys and client secrets:** For any API keys and client secrets used + inside ADK code, when running on a local compute environment use a local + `.env` file excluded from version control. When your agent is hosted or + otherwise in a production environment, use a secrets manager. For more + details on secrets managers, see the [next section](#secrets-manager). +* **Interactive authentication:** When using interactive three-legged auth + (3LO) OAuth or OpenID Connect (OIDC) for authentication to tools, write a + service on the client application to acquire, manage access, and refresh + tokens. Make sure to store these tokens against an authenticated user + identifier in an encrypted database. + +### Secrets manager services {#secrets-manager} + +For production environments, if not using an authentication manager service, you +should store credentials in a dedicated secret manager service to protect that +data. With this approach, a secret manager securely stores the credentials for +any tools or services accessed by the agent as needed, and those secrets are not +resident in agent's operating memory. For example, a custom ADK Tool using this +method would store only short-lived access tokens or secure references, and +retrieve longer-lived refresh tokens from the secrets manager when needed. When +selecting a secrets manager service, consider services from well-established +providers, such as [Google Cloud Secret Manager](https://cloud.google.com/security/products/secret-manager) or other secret management services. From b6f933c5d4968fd3a97573784fc1beac9ebac88f Mon Sep 17 00:00:00 2001 From: Joe Fernandez Date: Thu, 9 Apr 2026 16:03:48 +0000 Subject: [PATCH 2/2] updates from self-review --- docs/tools-custom/authentication.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/tools-custom/authentication.md b/docs/tools-custom/authentication.md index e08666eba..4656c92cf 100644 --- a/docs/tools-custom/authentication.md +++ b/docs/tools-custom/authentication.md @@ -28,7 +28,7 @@ There are several ways to manage authentication and credentials in ADK agents. Each of these methods carries some amount of risk, so you should carefully consider which approach best serves your application and customers. -### Recommended: Authentication manager services +### Recommended: Authentication manager services {#authentication-manager} When deploying agents to production hosted environments, your agent's ability to properly authenticate to restricted tools and services becomes more challenging @@ -58,15 +58,16 @@ and your own code, consider these recommendations: ### Secrets manager services {#secrets-manager} -For production environments, if not using an authentication manager service, you -should store credentials in a dedicated secret manager service to protect that -data. With this approach, a secret manager securely stores the credentials for -any tools or services accessed by the agent as needed, and those secrets are not -resident in agent's operating memory. For example, a custom ADK Tool using this -method would store only short-lived access tokens or secure references, and +For production environments, if you are not using an +[authentication manager](#authentication-manager) service, you should store +credentials in a dedicated secret manager service to protect that data. With +this approach, a secret manager securely stores the credentials for any tools or +services accessed by the agent as needed, and those secrets are not resident in +agent's operating memory. For example, a custom ADK Tool using this method would +have only short-lived access tokens or secure references in session memory, and retrieve longer-lived refresh tokens from the secrets manager when needed. When -selecting a secrets manager service, consider services from well-established -providers, such as +selecting a secrets manager, consider services from well-established providers, +such as [Google Cloud Secret Manager](https://cloud.google.com/security/products/secret-manager) or other secret management services.