Skip to content

Authentication

Two separate things are covered here: authenticating the agent's control connection to the server, and (optionally) gating who can reach a specific tunnel's traffic once it's exposed.

Agent Authentication (Control Connection)

The agent authenticates to the Connect Server's control connection using the identity configured under identity: in agent.yaml. The server validates the resulting token via jwt-validators. Supported identity types:

identity.type Use case
keycloak OIDC via a Keycloak realm
github GitHub OAuth (device flow)
flyio Fly.io machine identity (no interactive login)
githubactions GitHub Actions OIDC (no interactive login)
aws AWS machine identity (no interactive login)

agent.yaml:

identity:
  type: github
  client-id: "<your-github-oauth-app-client-id>"
  token-file: ~/.config/dioad/connect/auth.yaml

Machine-identity types (flyio, githubactions, aws) derive credentials from cloud metadata and don't need client-id/interactive login at all.

For interactive types, run connect agent auth to authenticate and populate token-file:

connect agent auth

See Agent Configuration Reference § identity for the full key reference.

Server side: validating incoming agents

Configured via connect.defaults.jwt-validators (or per-service, under connect.services[]) — see Server Configuration Reference § connect.defaults for the full key reference. If no jwt-validators are configured for a service, agent authentication is disabled for it (the server logs a warning at startup).

connect:
  defaults:
    jwt-validators:
      - url: "https://auth.example.com/realms/my-realm"
        audiences:
          - account

Each validator's type should match the agent identity type it's validating (keycloak, github, flyio, githubactions, aws — see the table above). Multiple validators can be listed to accept more than one identity type or provider.

For local development or smoke testing only (never production — see the warning in Server Configuration Reference § JWT Validators), a validator can use a static HMAC shared secret instead of a real OIDC issuer, skipping JWKS discovery entirely:

connect:
  defaults:
    jwt-validators:
      - hmac_secret: "your-secret-key-here"
        allow_insecure_hmac: true

Who an authenticated principal is then allowed to do (custom domains, network ACLs, etc.) is a separate, authorisation-layer concern — see Server Configuration Reference § Authorisation (inline, group-inline, dynamic privilege maps; inline.privileges also functions as an allow list, since only principals present in the map get any privileges).

Per-Tunnel Traffic Authentication

Independently of the above, the file and httpreverseproxy tunnel types (see Tunnel Types) can gate access to their own traffic with a config.authentication block (type: basic, github, hmac, jwt, or oidc). This protects who can reach the tunnel's content — it has nothing to do with agent-to-server authentication above.

Basic Auth

config:
  authentication:
    type: basic
    basic:
      htpasswd-file: .local-dev/htpasswd
      realm: "Dioad Connect"

Manage the htpasswd file with the htpasswd command (ships with https://httpd.apache.org and macOS):

htpasswd -B -C 10 <passwordfile> <user>

Other useful forms:

# Enter password on the command line
htpasswd -bnB -C 10 <username> <password>

# Enter password with verification prompt
htpasswd -nB -C 10 <username>

GitHub Auth

Authenticates viewers via GitHub OAuth, with an allow/deny list by GitHub username:

config:
  authentication:
    type: github
    github:
      client-id: "abcdefghijk1234567890"
      client-secret: "aabbccddeeffgghhiijjkkllmmnnooppqqrrsstt"
      principals:
        allow-list:
          - joeblogs
          - johndoe
        # deny-list: [...]   # alternative to allow-list

HMAC Auth

Verifies a per-request HMAC signature over a configured set of headers, rather than a bearer token:

config:
  authentication:
    type: hmac
    hmac:
      shared-key: "f91457f8-deadBeaf-11ea-8d00-93f9cfa8cc35"
      signed-headers:
        - X-Agent-ID
      allow-insecure-http: true   # only if TLS is terminated upstream (e.g. an NLB), not by connect itself

JWT Auth

Validates a bearer JWT via JWKS discovery against a configured issuer, and attaches the token's subject/claims to the request context for downstream use. issuer is required:

config:
  authentication:
    type: jwt
    jwt:
      issuer: "https://auth.example.com/realms/my-realm"
      audiences:
        - my-tunnel

The token is read from an Authorization: Bearer <token> header, or failing that a cookie named auth_token. Unlike agent-side JWT validation, this validator has no static HMAC shared-secret fallback — a real OIDC/JWKS issuer is always required. Like basic, github, and hmac, a request presenting no credential at all is rejected with 401, not just a request presenting an invalid one.

OIDC Auth

type: oidc accepts client credentials for an OIDC provider (client-id, client-secret, provider url) and redirects unauthenticated requests through a full login flow — /login starts it, a callback endpoint completes it, and cookies carry the resulting session. redirect-uri is required (the callback URL your OIDC provider redirects back to, and the path this flow is registered at on the tunnel).

Requires a domain you control, registered with your provider ahead of time. OIDC providers only redirect to a redirect-uri that's been pre-registered as an exact match — there's no way to register a URL before you know it. A reverse tunnel on the hosted connect.dioad.dev service gets a freshly generated subdomain per connection (e.g. hello.<account-id>.dioad.dev), which can't be predicted or pre-registered, so type: oidc isn't usable with that default domain. Set custom-domains on the tunnel to a domain you own, register that domain's callback URL with your OIDC provider, then point redirect-uri at it:

traffic:
  tunnels:
    - name: dashboard
      type: httpreverseproxy
      endpoint: https://connect.dioad.dev/connect/https
      custom-domains:
        - dashboard.example.com
      tls-server:
        acme:
          cache-directory: /path/to/.autocert
      config:
        target-url: http://127.0.0.1:8080
        authentication:
          type: oidc
          oidc:
            url: "https://auth.example.com/realms/my-realm"
            client-id: "<oidc-client-id>"
            client-secret: "<oidc-client-secret>"
            redirect-uri: "https://dashboard.example.com/callback"

basic, github, hmac, and jwt have no such constraint — none of them redirect through a pre-registered URL, so they work with any domain, including the hosted service's auto-assigned one.

Always pair with tls-server. Session cookies carry live access/refresh tokens. tls-server isn't enforced for this tunnel type by connect itself, but omitting it means those cookies (and, for type: jwt, bearer tokens) cross the public tunnel in plaintext — every example in this doc and in Tunnel Types configures tls-server; don't skip it for a tunnel using jwt or oidc auth.

Optional keys, with their defaults:

Key Default Purpose
login-path /login Path that starts the login flow
logout-path /logout Path that clears the session and signs out
scopes provider default OAuth2 scopes requested at login
token-cookie, state-cookie, refresh-cookie, token-expiry oidc_token, oidc_state, oidc_refresh, oidc_expires_in (each name/path/max-age) Override cookie name, path, or max-age individually — domain is left unset by default so the browser scopes it to the tunnel's own host
allow-insecure-cookies false Session cookies always carry the Secure attribute (HTTPS-only) regardless of any per-cookie secure value you set, unless this is true. Only relevant if you're testing the OIDC handler directly over plain http:// outside of a tunnel (e.g. hitting NewServer locally in a test) — a real tunnel is TLS-terminated per the note above, so production configs should never need this

login-path, the callback path (parsed from redirect-uri), and logout-path are always reachable unauthenticated — they're exempt from the auth gate itself, so the login flow can actually complete rather than redirecting into itself.

JWT vs OIDC: which to use

Both gate the same tunnel traffic, but they solve different problems for different kinds of caller — pick based on who's presenting credentials, and whether they can get one on their own.

type: jwt type: oidc
Caller A machine: script, CI job, another service, a CLI A human, in a browser
Token acquisition Caller already holds a valid JWT before the request — connect never issues one Connect drives the whole login: redirect to the provider, exchange the code, set session cookies
State Stateless — no cookies, no session to track Stateful — session/refresh/state cookies, with automatic token refresh as expiry nears
Interactive sign-in None — a request with no token is simply rejected with 401 Full redirect-based flow (login-path → provider → callback → session)
Logout N/A — there's no session to end logout-path clears the session cookies
Good fit APIs, webhooks, CI pipelines, service-to-service calls Dashboards, admin UIs, file shares meant for people to browse

If the caller is code that can obtain a token itself (its own OIDC client-credentials grant, or a token minted by an internal system) and send it as a header, use jwt — it's a single stateless check, nothing to manage on connect's side. If the caller is a person opening the tunnel URL in a browser with no token in hand, use oidc — it's the only one of the two that can take them from "no credential at all" to "authenticated" by itself.

Example: jwt for a CI pipeline calling an internal API

The tunnel:

config:
  authentication:
    type: jwt
    jwt:
      issuer: "https://auth.example.com/realms/my-realm"
      audiences:
        - my-tunnel

The caller obtains a token out of band — here, a service-account client-credentials grant against the same realm — and presents it on every request. Connect never sees anything resembling a login, only a bearer token:

TOKEN=$(curl -s -X POST "https://auth.example.com/realms/my-realm/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=ci-pipeline" \
  -d "client_secret=$CI_CLIENT_SECRET" \
  | jq -r .access_token)

curl -H "Authorization: Bearer $TOKEN" https://my-tunnel.example.com/api/status

No browser, no cookie — a single stateless call that either has a valid token or gets a 401.

Example: oidc for a human-facing dashboard

The tunnel:

config:
  authentication:
    type: oidc
    oidc:
      url: "https://auth.example.com/realms/my-realm"
      client-id: "my-tunnel-dashboard"
      client-secret: "<client-secret>"
      redirect-uri: "https://dashboard.example.com/callback"

A person just opens https://dashboard.example.com/ in a browser — no token handling on their part at all:

  1. No session cookie yet → redirected to /login.
  2. /login redirects to the realm's own sign-in page.
  3. After they authenticate, the realm redirects back to redirect-uri (/callback) with an authorization code.
  4. Connect exchanges the code for tokens and sets session cookies (oidc_token, oidc_refresh, oidc_state during the flow itself, oidc_expires_in).
  5. Every later request in that browser is authenticated via the session cookie, refreshed automatically as it nears expiry.
  6. Visiting /logout clears the cookies and ends the session.

No Authorization header ever appears here — the whole exchange happens through browser redirects and cookies, the opposite shape from the jwt example above.

Forwarding the Authenticated Principal Upstream

For httpreverseproxy tunnels, once config.authentication accepts a request, connect sets an X-Forwarded-User header on the request it sends to target-url, carrying the authenticated principal (username, GitHub login, JWT subject, etc. depending on the auth type). Your upstream application can read this header instead of re-implementing authentication itself.

X-Forwarded-User is set for all five auth types: basic, github, hmac, jwt, and oidc (the OIDC handler verifies the session's ID token and populates the principal from its subject claim).

The header is always stripped from the inbound request first, so a client can't set their own X-Forwarded-User and have it forwarded as if connect had vouched for it — your upstream only ever sees a value connect itself set after successful authentication, or no header at all.

file tunnels don't proxy to an upstream, so this doesn't apply to them.