Skip to main content

Authentication

fh uses whatever the deployment uses. fh config configure asks the same question interactively.

No authentication​

Community Edition, or authentication turned off:

fh config set base-url https://kpow.example.com
fh kafka topic list

Username and password​

HTTP Basic:

fh config set base-url https://kpow.example.com
fh config set username admin
fh config set password '<password>'

The password is stored in ~/.fh/config.yaml (mode 0600).

OpenID Connect​

fh auth login opens the browser at the deployment's identity provider and completes the authorization-code flow with PKCE. The API advertises its authorization server through OAuth 2.0 Protected Resource Metadata (RFC 9728), so the only inputs are the API URL and a public client id.

fh config set base-url https://kpow-api.example.com
fh config set oidc-client-id <public-client-id>
fh auth login
fh auth login --status      # identity and token expiry

Tokens are stored in ~/.fh/tokens.yaml (mode 0600), keyed by API URL, and refreshed automatically. Sign in again when the refresh token expires.

Browser callback

The authorization code returns to fh on http://localhost:49876/callback. Providers that enforce exact redirect URIs (Amazon Cognito does) need it registered on the client; redirect_mismatch in the browser means it is not. To use another port: fh config set oidc-callback-port 8778, or fh auth login --callback-port 8778.

Mode selection: a stored OpenID token, else Basic when a username is configured, else none. Override with --auth bearer or --auth basic (FH_AUTH).

Contexts​

A context is one deployment: URL, credentials, default tenant and cluster. Commands run against the current context unless --context or FH_CONTEXT names another.

fh config configure                    # creates a context and makes it current
fh config context list
fh config context use platform-dev
fh config context show [name]
fh config context rename old new
fh config context delete name
fh config switch context               # interactive picker
fh kafka topic list --context kpow-prod
FH_CONTEXT=kpow-prod fh kafka topic list
fh config set cluster abc123 --context kpow-prod   # writes to that context

Two contexts in ~/.fh/config.yaml:

current_context: platform-dev
theme: fh-dark
contexts:
  platform-dev:
    base_url: https://platform-api.dev.example.com
    oidc_client_id: <public-client-id>
    tenant: Everything
    cluster: 9FzrorVMTLCt0eq6RIOr8g
  kpow-prod:
    base_url: https://kpow.example.com
    username: admin
    password: secret
    cluster: lkc-j58q6w

Tokens are keyed by API URL, so two contexts on the same API share a sign-in. In the TUI, :ctx switches context for the session without changing the file.