From f24c8a3656fe79e933f5b317fa4fdb1528a8f4ff Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 11 Jun 2026 23:16:34 -0400 Subject: [PATCH 1/3] Document thv registry login and logout The registry login/logout commands existed in the CLI reference but weren't covered in the registry guide, leaving readers without instructions for authenticating to a protected remote registry. Add an "Authenticate to a protected registry" subsection under "Set a remote registry" that explains the interactive OAuth/OIDC login flow, the required and optional flags, the credential-clearing behavior when changing registries, and how to log out. Cross-link to the Registry Server authentication guide. Addresses docs-website issue #654 (high-priority gap #4). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/registry.mdx | 67 +++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/docs/toolhive/guides-cli/registry.mdx b/docs/toolhive/guides-cli/registry.mdx index dd2b8984..709053da 100644 --- a/docs/toolhive/guides-cli/registry.mdx +++ b/docs/toolhive/guides-cli/registry.mdx @@ -197,6 +197,73 @@ endpoint. ::: +### Authenticate to a protected registry + +Some remote registries require authentication before you can list, inspect, or +run their servers. ToolHive authenticates to these registries using an +interactive OAuth login backed by an OpenID Connect (OIDC) identity provider. If +your registry is open to anonymous access, you don't need to log in. + +To authenticate, run: + +```bash +thv registry login +``` + +This opens your browser to complete the OAuth flow with the registry's identity +provider. On success, ToolHive caches the resulting tokens and uses them +automatically for subsequent registry commands. + +The login command needs three pieces of configuration: the registry URL, the +OIDC issuer URL, and an OAuth client ID. If you already configured the registry +URL with +[`thv config set-registry`](../reference/cli/thv_config_set-registry.md) and ran +a previous login, ToolHive reuses the saved values, so you can run +`thv registry login` with no flags. Otherwise, supply the missing values as +flags. ToolHive validates them and saves them to your configuration before +starting the login flow. Passing `--issuer` and `--client-id` again later +overrides the saved OAuth settings: + +```bash +thv registry login \ + --registry https://registry.example.com/api \ + --issuer https://auth.example.com \ + --client-id my-app +``` + +The login command accepts the following flags: + +| Flag | Description | +| ------------------------ | ------------------------------------------------------------------------------- | +| `--registry` | Registry URL. Persisted to your configuration if not already set. | +| `--issuer` | OIDC issuer URL for the identity provider. ToolHive validates it via discovery. | +| `--client-id` | OAuth client ID registered with the identity provider. | +| `--audience` | OAuth audience parameter (optional). | +| `--scopes` | Comma-separated OAuth scopes to request. Defaults to `openid,offline_access`. | +| `-p, --allow-private-ip` | Allow `--registry` to reference a private IP address. Defaults to `false`. | + +:::note + +OAuth login applies only to remote registries (a URL or API endpoint). It isn't +supported for [local registry files](#set-a-local-registry-file). Supplying a +new `--registry` URL clears any previously saved credentials so that tokens are +never sent to the wrong server. + +::: + +When you're done, clear the cached credentials with: + +```bash +thv registry logout +``` + +This removes the cached OAuth tokens for the configured registry. The next +registry command that requires authentication prompts you to log in again. + +For details on configuring authentication on the server side, see +[Authentication configuration](../guides-registry/authentication.mdx) in the +Registry Server documentation. + ### Set a local registry file To configure ToolHive to use a local registry file, set the file path: From 0f5a041175e33072d4737423908dba0c79399672 Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Thu, 11 Jun 2026 23:49:53 -0400 Subject: [PATCH 2/3] Fix registry login flow ordering The section led with a bare `thv registry login`, which fails for a first-time user with no saved configuration. Lead with the full required-flags command and present the no-flags form as the follow-up for subsequent logins, matching the actual command behavior. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/registry.mdx | 31 +++++++++++---------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/docs/toolhive/guides-cli/registry.mdx b/docs/toolhive/guides-cli/registry.mdx index 709053da..4dc47de6 100644 --- a/docs/toolhive/guides-cli/registry.mdx +++ b/docs/toolhive/guides-cli/registry.mdx @@ -204,33 +204,26 @@ run their servers. ToolHive authenticates to these registries using an interactive OAuth login backed by an OpenID Connect (OIDC) identity provider. If your registry is open to anonymous access, you don't need to log in. -To authenticate, run: +Logging in needs three values: the registry URL, the OIDC issuer URL, and an +OAuth client ID. Supply them as flags the first time you authenticate. ToolHive +validates and saves them, then opens your browser to complete the OAuth flow: ```bash -thv registry login +thv registry login \ + --registry https://registry.example.com/api \ + --issuer https://auth.example.com \ + --client-id ``` -This opens your browser to complete the OAuth flow with the registry's identity -provider. On success, ToolHive caches the resulting tokens and uses them -automatically for subsequent registry commands. - -The login command needs three pieces of configuration: the registry URL, the -OIDC issuer URL, and an OAuth client ID. If you already configured the registry -URL with -[`thv config set-registry`](../reference/cli/thv_config_set-registry.md) and ran -a previous login, ToolHive reuses the saved values, so you can run -`thv registry login` with no flags. Otherwise, supply the missing values as -flags. ToolHive validates them and saves them to your configuration before -starting the login flow. Passing `--issuer` and `--client-id` again later -overrides the saved OAuth settings: +ToolHive caches the resulting tokens and reuses the saved settings, so later +logins (after you log out or your tokens expire) need no flags: ```bash -thv registry login \ - --registry https://registry.example.com/api \ - --issuer https://auth.example.com \ - --client-id my-app +thv registry login ``` +Pass `--issuer` or `--client-id` again to override the saved values. + The login command accepts the following flags: | Flag | Description | From 3fb9edfc9c53f5760970059441c0061bf0c758fb Mon Sep 17 00:00:00 2001 From: Dan Barr <6922515+danbarr@users.noreply.github.com> Date: Fri, 12 Jun 2026 10:26:20 -0400 Subject: [PATCH 3/3] Document OIDC auth flags on set-registry Add the --issuer/--client-id/--audience/--scopes OIDC flags and the --allow-private-ip flag on thv config set-registry, with a pointer to the registry login flow. Addresses medium-priority registry gaps in #654. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/toolhive/guides-cli/registry.mdx | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/toolhive/guides-cli/registry.mdx b/docs/toolhive/guides-cli/registry.mdx index 4dc47de6..44244d0d 100644 --- a/docs/toolhive/guides-cli/registry.mdx +++ b/docs/toolhive/guides-cli/registry.mdx @@ -197,6 +197,28 @@ endpoint. ::: +If your Registry Server requires authentication, you can configure the OIDC +settings at the same time by adding the `--issuer` and `--client-id` flags (with +optional `--audience` and `--scopes`). ToolHive saves these settings so you can +complete the login with +[`thv registry login`](#authenticate-to-a-protected-registry): + +```bash +thv config set-registry https://registry.example.com/api \ + --issuer https://auth.example.com \ + --client-id +``` + +To point at a Registry Server on a private IP address, such as a local +deployment during development, add the `-p, --allow-private-ip` flag. + +:::note + +Running `thv config set-registry` clears any previously configured registry +authentication, so reconfigure auth after changing the registry. + +::: + ### Authenticate to a protected registry Some remote registries require authentication before you can list, inspect, or