Protect the admin dashboard
Octopus ships a built-in admin dashboard — a web UI plus a JSON REST API for routes, health, metrics, plugins, config, and FARP services. It is served on the gateway's listen port and, out of the box, requires no authentication. Anyone who can reach the port can read your gateway's internals. This guide puts it behind an auth provider.
Set admin.auth_provider in any non-local deployment, and combine it with
admin.allowed_ips — an IP / CIDR / range allowlist that returns 403 to
non-matching clients — plus network-layer controls (NetworkPolicy, firewall).
See Admin configuration.
Define an auth provider for the dashboard01
Any auth provider works. A dedicated JWT provider for operators is a common choice; you could equally reuse an existing provider or use API key, mTLS, or forward auth.
auth_providers:
dashboard-auth:
type: jwt
secret: "${ADMIN_JWT_SECRET}"
algorithm: HS256
issuer: https://auth.example.comPoint the admin block at it02
Set admin.auth_provider to the name of that provider. Every /admin*
request is then run through it before the dashboard is dispatched;
unauthenticated requests get 401 Unauthorized.
admin:
auth_provider: dashboard-auth # must match an auth_providers keyStatic assets are exempt: requests whose path contains /static/ or /_next/
bypass the admin auth check so login-protected pages can still load their CSS
and JS. This is wired in the runtime.
Validate and run03
export ADMIN_JWT_SECRET=change-me
octopus validate -c gateway.yaml
octopus serve -c gateway.yamlThe full configuration (a real upstream is included so the gateway also proxies traffic — the admin protection works the same with or without it):
gateway:
listen: "0.0.0.0:8080"
upstreams:
- name: app
instances:
- id: app-1
host: 10.0.0.51
port: 8080
auth_providers:
dashboard-auth:
type: jwt
secret: "${ADMIN_JWT_SECRET}"
algorithm: HS256
issuer: https://auth.example.com
admin:
auth_provider: dashboard-auth
routes:
- path: /*
upstream: appVerify it is protected04
# Unauthenticated -> 401
curl -i http://localhost:8080/admin
# With a valid token from dashboard-auth
curl -i -H "Authorization: Bearer $ADMIN_TOKEN" http://localhost:8080/adminThe same protection covers the JSON API under /admin/api/* and the /__admin
alias. The dashboard's pages and endpoints are documented in
Admin dashboard and the
Admin API reference.
See also05
Admin dashboard — what the UI serves and where it mounts.
Admin configuration — the
adminblock schema.Secure an API with JWT — building the provider you reference here.
Security overview — all provider types you can point
auth_providerat.