diff --git a/.hugo/go.mod b/.hugo/go.mod index 649f7f63f..ed59ae282 100644 --- a/.hugo/go.mod +++ b/.hugo/go.mod @@ -2,4 +2,7 @@ module github.com/googleapis/genai-toolbox go 1.23.2 -require github.com/google/docsy v0.11.0 // indirect +require ( + github.com/google/docsy v0.11.0 // indirect + github.com/martignoni/hugo-notice v0.0.0-20240707105359-40327ac00cc4 // indirect +) diff --git a/.hugo/go.sum b/.hugo/go.sum index 558b7c83e..987520b6c 100644 --- a/.hugo/go.sum +++ b/.hugo/go.sum @@ -1,4 +1,6 @@ github.com/FortAwesome/Font-Awesome v0.0.0-20240716171331-37eff7fa00de/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo= github.com/google/docsy v0.11.0 h1:QnV40cc28QwS++kP9qINtrIv4hlASruhC/K3FqkHAmM= github.com/google/docsy v0.11.0/go.mod h1:hGGW0OjNuG5ZbH5JRtALY3yvN8ybbEP/v2iaK4bwOUI= +github.com/martignoni/hugo-notice v0.0.0-20240707105359-40327ac00cc4 h1:lxS0B1ta9/uW+orrnvsGHMCC0TgN4DymEgdlb0PL/uU= +github.com/martignoni/hugo-notice v0.0.0-20240707105359-40327ac00cc4/go.mod h1:MIQPOMgEcbyRC0gNLzQFSgrS+wIy3RuQ/HbaZYtTOKU= github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0= diff --git a/.hugo/hugo.toml b/.hugo/hugo.toml index f55468471..2fd2553ce 100644 --- a/.hugo/hugo.toml +++ b/.hugo/hugo.toml @@ -22,6 +22,8 @@ enableRobotsTXT = true [[module.imports]] path = "github.com/google/docsy" disable = false + [[module.imports]] + path = "github.com/martignoni/hugo-notice" [params] copyright = "Google LLC" diff --git a/docs/authSources/README.md b/docs/authSources/README.md deleted file mode 100644 index 636b0d293..000000000 --- a/docs/authSources/README.md +++ /dev/null @@ -1,87 +0,0 @@ -# AuthSources - -`AuthSources` represent authentication sources that a tool can interact with. -Toolbox supports authentication providers that conform to the [OpenID Connect -(OIDC) protocol](https://openid.net/developers/how-connect-works/). You can -define Auth Sources as a map in the `authSources` section of your `tools.yaml` -file. Typically, an Auth Source is required for the following features: - -- [Authenticated parameters](../tools/README.md#authenticated-parameters) -- [Authorized tool call](../tools/README.md#authorized-tool-call) - -## Example - -```yaml -authSources: - my-google-auth: - kind: google - clientId: YOUR_GOOGLE_CLIENT_ID -``` - -> [!TIP] -> If you are accessing Toolbox with multiple applications, each application -> should register their own Client ID even if they use the same `kind` of auth -> provider. -> -> Here's an example: -> -> ```yaml -> authSources: -> my_auth_app_1: -> kind: google -> clientId: YOUR_CLIENT_ID_1 -> my_auth_app_2: -> kind: google -> clientId: YOUR_CLIENT_ID_2 -> -> tools: -> my_tool: -> parameters: -> - name: user_id -> type: string -> authSources: -> - name: my_auth_app_1 -> field: sub -> - name: my_auth_app_2 -> field: sub -> ... -> -> my_tool_no_param: -> authRequired: -> - my_auth_app_1 -> - my_auth_app_2 -> ... -> ``` - -## Kinds of authSources - -We currently support the following types of kinds of `authSources`: - -- [Google OAuth 2.0](./google.md) - Authenticate with a Google-signed OpenID - Connect (OIDC) ID token. - -## ID Token - -The OIDC authentication workflow transmit user information with ID tokens. ID -tokens are JSON Web Tokens (JWTs) that are composed of a set of key-value pairs -called -[claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). -ID tokens can include claims such as user ID, user name, user emails etc. After -specifying `authSources`, you can configure your tool's authenticated parameters -by following this [guide](../tools/README.md#authenticated-parameters). - -## Usage - -`AuthSources` can be used for both `authorization` and `authentication`: - -- `Authorization` verifies that a Tool invocation request includes the necessary - authentication token. Add an authorization layer to your Tool calling by - configuring the [authorized Tool - call](../tools/README.md#authorized-tool-call). -- `Authentication` verifies the user's identity in a Tool's query to the - database. Configure [authenticated - parameters](../tools/README.md#authenticated-parameters) to auto-populate your - Tool parameters from user login info. - -After confuring your `authSources`, use Toolbox Client SDK to add your `ID tokens` to -the header of a Tool invocation request. diff --git a/docs/authSources/google.md b/docs/authSources/google.md deleted file mode 100644 index 73c07c8ca..000000000 --- a/docs/authSources/google.md +++ /dev/null @@ -1,25 +0,0 @@ -# Google OAuth 2.0 - -To use Google as your Toolbox authentication provider, you could integrate -Google sign-in into your application by following this -[guide](https://developers.google.com/identity/sign-in/web/sign-in). After -setting up the Google sign-in workflow, you should have registered your -application and retrieved a [Client -ID](https://developers.google.com/identity/sign-in/web/sign-in#create_authorization_credentials). -Configure your auth source in `tools.yaml` with the `Client ID`. - -## Example - -```yaml -authSources: - my-google-auth: - kind: google - clientId: YOUR_GOOGLE_CLIENT_ID -``` - -## Reference - -| **field** | **type** | **required** | **description** | -|-----------|:--------:|:------------:|------------------------------------------------------------------------------| -| kind | string | true | Must be "google". | -| clientId | string | true | Client ID of your application from registering your application. | diff --git a/docs/en/resources/authSources/_index.md b/docs/en/resources/authSources/_index.md new file mode 100644 index 000000000..b5057e540 --- /dev/null +++ b/docs/en/resources/authSources/_index.md @@ -0,0 +1,92 @@ +--- +title: "AuthSources" +type: docs +weight: 1 +description: > + AuthSources represent services that handle authentication and authorization. +--- + +AuthSources represent services that handle authentication and authorization. It +can primarily be used by [Tools](../tools) in two different ways: + +- [**Authorized Invocation**][auth-invoke] is when a tool + to be validate by the auth service before the call can be invoked. Toolbox + will rejected an calls that fail to validate or have an invalid token. +- [**Authenticated Parameters**][auth-paramsgit ] replace the + value of a parameter with a field from an [OIDC][openid-claims] claim. Toolbox + will automatically resolve the ID token provided by the client and replace the + parameter in the tool call. + +[openid-claims]: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims +[auth-invoke]: ../tools/#authorized-invocations +[auth-params]: ../tools/#authenticated-parameters + +## Example + +The following configurations are placed at the top level of a `tools.yaml` file. + +{{< notice tip >}} +If you are accessing Toolbox with multiple applications, each + application should register their own Client ID even if they use the same + "kind" of auth provider. +{{< /notice >}} + +```yaml +authSources: + my_auth_app_1: + kind: google + clientId: YOUR_CLIENT_ID_1 + my_auth_app_2: + kind: google + clientId: YOUR_CLIENT_ID_2 +``` + +After you've configured an `authSource` you'll, need to reference it in the +configuration for each tool that should use it: +- **Authorized Invocations** for authorizing a tool call, [use the + `requiredAuth` field in a tool config][auth-invoke] +- **Authenticated Parameters** for using the value from a ODIC claim, [use the + `authSources` field in a parameter config][auth-params] + + +## Specifying ID Tokens from Clients + +After [configuring](#example) your `authSources` section, use a Toolbox SDK to +add your ID tokens to the header of a Tool invocation request. When specifying a +token you will provide a function (that returns an id). This function is called +when the tool is invoked. This allows you to cache and refresh the ID token as +needed. + +### Specifying tokens during load +{{< tabpane >}} +{{< tab header="LangChain" lang="Python" >}} +async def get_auth_token(): + # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow) + # This example just returns a placeholder. Replace with your actual token retrieval. + return "YOUR_ID_TOKEN" # Placeholder + +# for a single tool use: +authorized_tool = await toolbox.load_tool("my-tool-name", auth_tokens={"my_auth": get_auth_token}) + +# for a toolset use: +authorized_tools = await toolbox.load_toolset("my-toolset-name", auth_tokens={"my_auth": get_auth_token}) +{{< /tab >}} +{{< /tabpane >}} + + +### Specifying tokens for existing tools + +{{< tabpane >}} +{{< tab header="LangChain" lang="Python" >}} +tools = await toolbox.load_toolset() +# for a single token +auth_tools = [tool.add_auth_token("my_auth", get_auth_token) for tool in tools] +# OR, if multiple tokens are needed +authorized_tool = tools[0].add_auth_tokens({ + "my_auth1": get_auth1_token, + "my_auth2": get_auth2_token, +}) +{{< /tab >}} +{{< /tabpane >}} + +## Kinds of Auth Sources diff --git a/docs/en/resources/authSources/google.md b/docs/en/resources/authSources/google.md new file mode 100644 index 000000000..b75f22058 --- /dev/null +++ b/docs/en/resources/authSources/google.md @@ -0,0 +1,54 @@ +--- +title: "Google Sign-In" +type: docs +weight: 1 +description: > + Use Google Sign-In for Oauth 2.0 flow and token lifecycle. +--- + +## Getting Started + +Google Sign-In manages the OAuth 2.0 flow and token lifecycle. To integrate the +Google Sign-In workflow to your web app [follow this guide][gsi-setup]. + +After setting up the Google Sign-In workflow, you should have registered your +application and retrieved a [Client ID][client-id]. Configure your auth source +in with the `Client ID`. + +[gsi-setup]: https://developers.google.com/identity/sign-in/web/sign-in +[client-id]: https://developers.google.com/identity/sign-in/web/sign-in#create_authorization_credentials + +## Behavior + +### Authorized Invocations + +When using [Authorized Invocations][auth-invoke], a tool will be +considered authorized if it has a valid Oauth 2.0 token that matches the Client +ID. + +[auth-invoke]: ../tools/#authorized-invocations + +### Authenticated Parameters + +When using [Authenticated Parameters][auth-params], any [claim provided by the +id-token][provided-claims] can be used as a source for the parameter. + +[auth-params]: ../tools/#authenticated-phugarameters +[provided-claims]: + https://developers.google.com/identity/openid-connect/openid-connect#obtaininguserprofileinformation + +## Example + +```yaml +authSources: + my-google-auth: + kind: google + clientId: YOUR_GOOGLE_CLIENT_ID +``` + +## Reference + +| **field** | **type** | **required** | **description** | +|-----------|:--------:|:------------:|------------------------------------------------------------------| +| kind | string | true | Must be "google". | +| clientId | string | true | Client ID of your application from registering your application. |