fix: use automatic OAuth issuer discovery

Align tutorial defaults and OAuth guidance with orca-cli PR #8.
Keep issuer selection optional and update all three paths' error hints.

Assisted-by: Codex

Author: jiangpengcheng

.env.example

@@ -29,12 +29,14 @@ SN_MCP_URL=
 
 # MCP authentication: oauth (default) or static_bearer for API-key MCP servers.
 # All three tutorial paths call ork for the first OAuth login, then reuse the
-# credential stored in the vault. Install ork with MCP OAuth proxy support.
+# credential stored in the vault. Install ork with the OAuth discovery support
+# from orca-cli PR #8 (or current main).
 SN_MCP_AUTH=oauth
 
-# Expected issuer for the StreamNative OAuth proxy (from trusted provider setup).
-# For a different MCP provider, set its issuer or leave empty for discovery.
-SN_MCP_OAUTH_ISSUER=https://auth.streamnative.cloud/
+# Optional authorization server selection. Leave empty for automatic discovery.
+# If multiple servers are advertised, copy one exact authorization_servers value
+# from the MCP protected-resource metadata; do not substitute the metadata issuer.
+SN_MCP_OAUTH_ISSUER=
 SN_MCP_OAUTH_SCOPE="openid profile email offline_access"
 
 # ------------------------------------------------------------- your choices --

README.md

@@ -61,8 +61,14 @@ stored OAuth credential. This check verifies MCP initialization; L3/L4 exercise
 the actual SQL tools. A failed check prints its fix. Still stuck after two tries?
 Raise your hand.
 
-For StreamNative SQL Workspace MCP, keep `SN_MCP_AUTH=oauth` and the issuer/scope
-settings from `.env.example`. `SN_API_KEY` authenticates the hosted Agent Engine,
+For StreamNative SQL Workspace MCP, keep `SN_MCP_AUTH=oauth`, leave
+`SN_MCP_OAUTH_ISSUER` empty for automatic discovery, and use the scope from
+`.env.example`. Use an `ork` build containing [PR #8](https://github.com/orca-ae/orca-cli/pull/8)
+or current main. Its discovery accepts HTTPS issuer aliases within the same
+registrable domain and port. Only set `SN_MCP_OAUTH_ISSUER` when selecting one
+of multiple advertised `authorization_servers`; copy that advertised value
+exactly rather than the final issuer in authorization-server metadata.
+`SN_API_KEY` authenticates the hosted Agent Engine,
 Kafka and Schema Registry; it is not the OAuth MCP access token. All three paths
 use `ork` for the first MCP login, then reuse the live credential for the same URL
 and auth type from `.orca-state/<participant>.json`. Tokens stay in the server-side
@@ -332,7 +338,7 @@ ork agent update "$AGENT_ID" --version 1 --model "$ORCA_MODEL" \
 ork agent vaults create --display-name hello-vault-ana -o json
 ork agent vaults credentials create --vault "$VAULT_ID" --display-name streamnative-mcp \
   --mcp-server-url "$SN_MCP_URL" \
-  --oauth-issuer "$SN_MCP_OAUTH_ISSUER" --oauth-scope "$SN_MCP_OAUTH_SCOPE" -o json
+  --oauth-scope "$SN_MCP_OAUTH_SCOPE" -o json
 
 ork agent sessions create --agent "$AGENT_ID" --agent-version 2 \
   --environment-id "$ENVIRONMENT_ID" --vault-id "$VAULT_ID" --title "L3: live context" -o json
@@ -408,7 +414,7 @@ action, and you have your hackathon project. Ideas and next steps:
 | `relation "avro.security.login_events" does not exist` | Select your team's database and update the quoted Avro source in both L2 SQL files to match `LOGIN_TOPIC` in `.env`. |
 | The agent can't find `login_failures` | Create the view in your team's database (L2, step 2); the agent looks it up there. |
 | `[error]` lines from MCP tools in L3 | Check `SN_MCP_URL` and `SN_MCP_AUTH`, finish the OAuth login, then rerun the doctor. |
-| OAuth issuer mismatch / unsupported client authentication | Install an `ork` build with OAuth proxy and `client_secret_basic` support; verify `SN_MCP_OAUTH_ISSUER` against trusted provider setup. |
+| OAuth issuer mismatch / unsupported client authentication | Use current `ork` main or PR #8 and leave `SN_MCP_OAUTH_ISSUER` empty for StreamNative discovery. An explicit issuer must match an advertised authorization server. `--oauth-allow-issuer-mismatch` is only for trusted servers whose metadata issuer crosses registrable domains; StreamNative does not need it. |
 | `Cannot reach the Agent Engine` | `ORCA_BASE_URL` must be the host root from your card, with no `/v1`. |
 | The agent answers from memory instead of querying | Ask again, "check the view first". The system prompt tells it to always query. |
 

cli/lib.sh

@@ -216,7 +216,7 @@ ensure_vault() {  # ensure_vault <name>
       [ -z "${SN_MCP_OAUTH_SCOPE:-}" ] || oauth_args+=(--oauth-scope "$SN_MCP_OAUTH_SCOPE")
       # Keep the browser URL and callback progress visible; tokens go directly to the vault.
       ork agent vaults credentials create "${oauth_args[@]}" -o json ||
-        hello_die "MCP OAuth authorization failed. Check the ork error above and SN_MCP_OAUTH_ISSUER, then rerun L3/L4."
+        hello_die "MCP OAuth authorization failed. Check the ork error above; normally leave SN_MCP_OAUTH_ISSUER empty for discovery, then rerun L3/L4."
     else
       auth=$(jq -cn --arg url "$SN_MCP_URL" --arg token "$SN_API_KEY" '{type: "static_bearer", mcp_server_url: $url, token: $token}')
       ork_json agent vaults credentials create --vault "$VAULT_ID" --display-name streamnative-mcp --auth-json "$auth" \

docs/before-you-arrive.md

@@ -11,9 +11,13 @@ can pick a different one.
 
 Everyone also needs `git`, a terminal, and [`ork`](https://github.com/orca-ae/orca-cli)
 for the first OAuth MCP login in L3/L4, including the Python and TypeScript paths.
-Use a build with MCP OAuth proxy issuer pinning and `client_secret_basic` support;
-check `ork agent vaults credentials create --help` for `--oauth-issuer` and
-`--oauth-client-secret-file`. The browser flow stores tokens directly in the vault.
+Use current `orca-cli` main or a build containing [PR #8](https://github.com/orca-ae/orca-cli/pull/8).
+Check `ork agent vaults credentials create --help` for `--oauth-issuer` and
+`--oauth-allow-issuer-mismatch`. Automatic discovery handles StreamNative's
+same-domain proxy issuer aliases and dynamic client authentication. Leave
+`SN_MCP_OAUTH_ISSUER` empty for this flow; `--oauth-issuer` only selects an
+authorization server advertised by the MCP server when a choice is needed.
+The browser flow stores tokens directly in the vault.
 On Windows, use WSL or Git Bash for the CLI path.
 
 ## 1. Get the code

python/common.py

@@ -192,7 +192,7 @@ def authorize_mcp(vault_id: str, config: Config) -> None:
     except OSError:
         raise ConfigError("Install ork with MCP OAuth proxy support and put it on PATH (see docs/before-you-arrive.md).") from None
     if result.returncode:
-        raise ConfigError("MCP OAuth authorization failed. Check the ork error above and SN_MCP_OAUTH_ISSUER, then rerun L3/L4.")
+        raise ConfigError("MCP OAuth authorization failed. Check the ork error above; normally leave SN_MCP_OAUTH_ISSUER empty for discovery, then rerun L3/L4.")
 
 
 def ensure_vault(client: Any, state: State, name: str, config: Config) -> str:

typescript/src/common.ts

@@ -330,7 +330,7 @@ export function authorizeMcp(vaultId: string, config: Config): void {
   // No shell and no credentials in argv; OAuth tokens are never read by this script.
   const result = spawnSync('ork', args, { env, stdio: 'inherit' });
   if (result.error) throw new ConfigError('Install ork with MCP OAuth proxy support and put it on PATH (see docs/before-you-arrive.md).');
-  if (result.status !== 0) throw new ConfigError('MCP OAuth authorization failed. Check the ork error above and SN_MCP_OAUTH_ISSUER, then rerun L3/L4.');
+  if (result.status !== 0) throw new ConfigError('MCP OAuth authorization failed. Check the ork error above; normally leave SN_MCP_OAUTH_ISSUER empty for discovery, then rerun L3/L4.');
 }
 
 /** The remembered resource, or null if it was never created, deleted, or archived. */