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:
- No session cookie yet → redirected to
/login. /loginredirects to the realm's own sign-in page.- After they authenticate, the realm redirects back to
redirect-uri(/callback) with an authorization code. - Connect exchanges the code for tokens and sets session cookies (
oidc_token,oidc_refresh,oidc_stateduring the flow itself,oidc_expires_in). - Every later request in that browser is authenticated via the session cookie, refreshed automatically as it nears expiry.
- Visiting
/logoutclears 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.