Wardengate

Administer

First-login setup

The installer brings the control plane online with the bare minimum — a single bootstrap account, a self-signed hostname, and no tenants. This page walks through the small sequence of steps that turns that skeleton into a usable deployment, in the order we recommend running them.

Before you start

You should already have finished the install and captured three pieces of output the installer prints on its final run: the bootstrap URL, the one-time bootstrap password, and the license activation code. If any of these scrolled off, re-run wgctl bootstrap show from the control plane host — the values live on disk until the first successful login.

  • Network path from your browser to the control plane admin port.
  • A DNS record you control for the user-facing hostname.
  • Your Wardengate license file, delivered as a signed JWT.
  • Credentials or metadata URL for the identity provider you plan to wire up.

Step 1: sign in as the bootstrap admin

Browse to the URL the installer printed. It looks something like https://<host>:8443/bootstrap and accepts only the built-in root principal. The bootstrap password is single-use: the control plane forces a reset on the first successful form submit. Pick a long passphrase — this credential is a break-glass safety net, not a daily driver.

# bootstrap password can also be rotated from the CLI
wgctl bootstrap reset-password \
  --current "$(cat /etc/wardengate/bootstrap.secret)" \
  --new-from-stdin

Step 2: set the canonical base URL

The base URL is the hostname users and IdP callbacks will hit. It is embedded in SAML assertion consumer URLs, OIDC redirect URIs, SCIM endpoints, and every link in outbound emails. Set it once, before wiring an IdP; changing it after SAML is configured invalidates every assertion in flight.

wgctl system set \
  --base-url https://wardengate.example.com \
  --admin-url https://wardengate.example.com/admin \
  --proxy-trusted-cidrs 10.0.0.0/8

If you terminate TLS at a load balancer, add the LB CIDR to --proxy-trusted-cidrs so the control plane honours the forwarded client IP and scheme headers. Misconfigured proxy trust is the most common cause of cookie-on-wrong-domain bugs.

Step 3: upload the license

The license is a signed JWT that carries your seat entitlement, expiry, and feature flags. Without it, the control plane runs in a restricted evaluation mode that caps you at five targets and five users. Upload the file through the console, or from the CLI:

wgctl license apply --file wardengate.license.jwt
wgctl license show

# expected
# holder          ACME Corporation
# seats           500
# features        recording,approvals,scim,siem-export
# issued          2026-03-04
# expires         2027-03-04

Step 4: create the first organization

An organization is the top-level tenancy boundary. Even a single-team deployment needs one — the bootstrap admin lives outside every org and cannot itself broker sessions. Create one called something you will still recognise in three years.

apiVersion: wardengate/v1
kind: Organization
metadata:
  name: acme
spec:
  displayName: ACME Corporation
  defaultTimezone: Europe/Berlin
  contactEmail: security@acme.example
  features:
    recording: true
    approvals: true
wgctl apply -f acme-org.yaml

Step 5: connect a default identity provider

The bootstrap admin cannot be the daily operator. Wire your IdP before you invite anyone else. A minimal SAML connection is enough to let humans sign in; SCIM and richer attribute mapping can come later.

apiVersion: wardengate/v1
kind: IdentityProvider
metadata:
  name: acme-saml
  organization: acme
spec:
  protocol: saml
  metadataUrl: https://idp.acme.example/saml/wardengate/metadata
  attributeMapping:
    email: email
    displayName: name
    groups: memberOf
  jit:
    createUsers: true
    defaultRoles: ["user"]

Test the SSO round trip in a private browser window before the next step — signing yourself out of a working console is a painful way to discover that the assertion consumer URL is mis-typed.

Step 6: create the first admin role

Bind an IdP group to the built-in OrgAdmin role. The group should be small — three to five people is a healthy starting point — and should map onto the team that owns the platform, not a project team.

apiVersion: wardengate/v1
kind: RoleBinding
metadata:
  name: org-admins
  organization: acme
spec:
  role: OrgAdmin
  subjects:
    - kind: Group
      name: wardengate-admins

Sign out of the bootstrap account, sign back in through SSO, and verify you land in the console with the org admin badge. Only then should you move on.

Step 7: sanity-check with a test session

Pick a throwaway Linux host — a spare VM, a container in a lab subnet — and onboard it as a target. Connect through a gateway, type a few commands, and disconnect. The goal here is to exercise the brokered path end-to-end: auth, policy, gateway, host-key verification, recording, audit.

wgctl target create \
  --org acme --name lab-01 --protocol ssh \
  --address 10.99.0.12:22 --account ubuntu

wgctl policy apply -f - <<'EOF'
apiVersion: wardengate/v1
kind: Policy
metadata:
  name: lab-access
  organization: acme
spec:
  principals: { groups: ["wardengate-admins"] }
  targets:   { names: ["lab-01"] }
  protocols: ["ssh"]
  accounts:  ["ubuntu"]
  recording: { mode: full }
EOF

wgctl connect ssh lab-01 --account ubuntu

When you disconnect, open Audit → Sessions in the console, play the recording back, and confirm the event stream matches what you did. A working first session means the control plane, the gateway, identity, policy, and storage are all on speaking terms.

Step 8: disable the bootstrap admin

With a working org admin role, rotate and disable the bootstrap account. It cannot be deleted — it exists for recovery — but you can freeze it and park the password in your secrets manager.

wgctl bootstrap disable
wgctl bootstrap show

# bootstrap   disabled
# last-used   2026-04-19T09:12:47Z

What to do next

The install is usable. The remaining onboarding is the long tail — wiring richer IdP attributes, onboarding real targets, defining MFA and approval policies, and enabling the notification channels your team lives in.

Next steps