Description
When registering a gateway with an https:// endpoint, the CLI defaults to the Cloudflare Access edge-auth flow — opening a browser to /auth/connect and waiting for a CF_Authorization cookie. Without Cloudflare Access in front of the gateway, this hangs indefinitely with an "Authenticating..." spinner and times out after 120 seconds with no actionable guidance.
The CLI supports OIDC authentication via --oidc-issuer, which works correctly, but:
- There is no indication that the edge-auth flow requires Cloudflare Access specifically
- When the flow fails (no CF cookie arrives), the timeout message doesn't suggest alternatives
- The user must already know about
--oidc-issuer to use OIDC — it's not discoverable from the failure path
Steps to Reproduce
- Deploy the gateway on any Kubernetes cluster without Cloudflare Access (OpenShift, GKE, EKS, k3d...)
- Configure OIDC on the gateway (e.g., Keycloak)
- Run
openshell gateway add https://<endpoint> --gateway-insecure
Expected: Either auto-detect the gateway's auth mode, or fail fast with a message like:
Edge authentication requires Cloudflare Access. If your gateway uses OIDC, re-run with:
openshell gateway add <endpoint> --oidc-issuer <issuer-url>
Actual: Browser opens to /auth/connect, shows "Authenticating..." spinner for 120 seconds, then:
⚠ Authentication skipped: authentication timed out after 120 seconds.
Try again with: openshell gateway login
Re-running gateway login produces the same result.
Root Cause
The /auth/connect handler (crates/openshell-server/src/auth/http.rs:87-141) checks for a CF_Authorization cookie. Without Cloudflare, the cookie never arrives, and the page polls via <meta http-equiv="refresh"> indefinitely. The CLI has no way to distinguish "Cloudflare is slow" from "Cloudflare isn't there."
Working OIDC Flow
OIDC works correctly when the user knows to pass the flag:
openshell gateway add https://<endpoint> --gateway-insecure \
--oidc-issuer https://keycloak.example.com/realms/openshell \
--oidc-client-id openshell-cli
This opens the Keycloak login page, authenticates via PKCE, and stores the token. The issue is purely about discoverability and the default behavior for HTTPS endpoints.
Proposed Improvements
1. Auto-detect auth mode (ideal)
The gateway already exposes its OIDC config at startup. The CLI could query a metadata/health endpoint during gateway add to detect whether the gateway has OIDC configured, and automatically use the OIDC flow instead of the CF edge-auth flow.
2. Fail fast with guidance (minimal)
If the /auth/connect page doesn't receive a CF_Authorization cookie within ~10 seconds, the server could return an error page instead of polling forever:
Authentication requires an edge proxy (e.g., Cloudflare Access).
If your gateway uses OIDC, register with:
openshell gateway add <endpoint> --oidc-issuer <url>
3. Documentation (immediate)
Update the Kubernetes/OpenShift deployment docs to show the OIDC flow as the primary auth method for direct deployments, and clarify that the default HTTPS browser flow is designed for Cloudflare Access only.
Environment
- Tested on OpenShift 4.21.3 (ROSA HCP) with passthrough route + Keycloak OIDC
- OpenShell gateway v0.0.70 chart, CLI v0.0.45
- OIDC flow works correctly once
--oidc-issuer is passed
Related
Description
When registering a gateway with an
https://endpoint, the CLI defaults to the Cloudflare Access edge-auth flow — opening a browser to/auth/connectand waiting for aCF_Authorizationcookie. Without Cloudflare Access in front of the gateway, this hangs indefinitely with an "Authenticating..." spinner and times out after 120 seconds with no actionable guidance.The CLI supports OIDC authentication via
--oidc-issuer, which works correctly, but:--oidc-issuerto use OIDC — it's not discoverable from the failure pathSteps to Reproduce
openshell gateway add https://<endpoint> --gateway-insecureExpected: Either auto-detect the gateway's auth mode, or fail fast with a message like:
Actual: Browser opens to
/auth/connect, shows "Authenticating..." spinner for 120 seconds, then:Re-running
gateway loginproduces the same result.Root Cause
The
/auth/connecthandler (crates/openshell-server/src/auth/http.rs:87-141) checks for aCF_Authorizationcookie. Without Cloudflare, the cookie never arrives, and the page polls via<meta http-equiv="refresh">indefinitely. The CLI has no way to distinguish "Cloudflare is slow" from "Cloudflare isn't there."Working OIDC Flow
OIDC works correctly when the user knows to pass the flag:
This opens the Keycloak login page, authenticates via PKCE, and stores the token. The issue is purely about discoverability and the default behavior for HTTPS endpoints.
Proposed Improvements
1. Auto-detect auth mode (ideal)
The gateway already exposes its OIDC config at startup. The CLI could query a metadata/health endpoint during
gateway addto detect whether the gateway has OIDC configured, and automatically use the OIDC flow instead of the CF edge-auth flow.2. Fail fast with guidance (minimal)
If the
/auth/connectpage doesn't receive aCF_Authorizationcookie within ~10 seconds, the server could return an error page instead of polling forever:3. Documentation (immediate)
Update the Kubernetes/OpenShift deployment docs to show the OIDC flow as the primary auth method for direct deployments, and clarify that the default HTTPS browser flow is designed for Cloudflare Access only.
Environment
--oidc-issueris passedRelated
crates/openshell-server/src/auth/http.rs— edge auth handlercrates/openshell-cli/src/run.rs:940-960— gateway type detection logiccrates/openshell-cli/src/auth.rs— browser auth flow (CF-specific)crates/openshell-cli/src/oidc_auth.rs— OIDC browser flow (works)