Skip to content

Teleport single sign-on

Tenantry can authenticate each request with the JWT that Teleport signs in the Teleport-Jwt-Assertion header (verified against the cluster's JWKS). The administrator then signs in to Teleport, with its MFA, and opens Tenantry as an application.

Tenantry must be reachable only through Teleport

Otherwise the JWT is not the only way in. Bind Tenantry to 127.0.0.1 or to the Teleport Docker network, and publish it only as a Teleport application.

Steps

  1. Register Tenantry as a Teleport application (tctl create -f) with a label such as app: Tenantry and a uri, for example https://tenantry.acme.ch:443. The master bundle publishes Tenantry with tenantry-app.yaml (uri: http://tenantry:8443, on the Docker network); the SSO options below require an https:// audience, so for SSO register a separate application with an https:// URI.
  2. Create a role that grants access to the application (app_labels: {app: Tenantry}), for example tenantry-admin, and assign it to the operators. Require require_session_mfa.
  3. Install (or re-run install.sh) with the SSO options. The audience must equal the URI of the application registered in Teleport, and the issuer is the cluster name:
sudo scripts/install.sh --name acme --public-url https://tenantry.acme.ch \
  --teleport-local auto --expose proxy \
  --sso-issuer teleport.acme.ch --sso-audience https://tenantry.acme.ch:443 \
  --sso-jwks-url https://teleport.acme.ch/.well-known/jwks.json \
  --sso-roles tenantry-admin,tenantry-tech --sso-admin-roles tenantry-admin \
  --trust-proxy <proxy address as Tenantry sees it> --sso-only --version <x.y.z>

--sso-admin-roles names the MSP administrators among --sso-roles (TELEPORT_JWT_ADMIN_ROLES). It is explicit: there is no fallback to the allowed roles. Empty (or omitted with --non-interactive) means nobody signing in through Teleport is an administrator: every SSO user is a technician scoped per client, and the local password login stays the break-glass administrator (unless --sso-only). In a terminal the installer asks for it, and the guided mode (step 5) asks with tenantry-admin as the suggestion. See Technicians and client scopes.

Without --sso-only, the password remains a fallback. With it, password sign-in is refused (403). If the Teleport proxy uses a private CA, add --ca-file (otherwise the JWKS fetch fails).

The settings end up in .env as TELEPORT_JWT_ENABLED, TELEPORT_JWT_ISSUER, TELEPORT_JWT_AUDIENCE, TELEPORT_JWT_JWKS_URL, TELEPORT_JWT_ALLOWED_ROLES, TELEPORT_JWT_ADMIN_ROLES and TELEPORT_ONLY.

Reverse proxy and TRUST_PROXY

Behind a reverse proxy or Teleport Application Access, --trust-proxy (TRUST_PROXY) names the proxy whose X-Forwarded-For Tenantry trusts: its IP address or CIDR as Tenantry sees it (a hop count is still accepted but trusts any peer, with a warning). By default X-Forwarded-For is ignored (true is refused): all requests then look like they come from the proxy, so rate limiting and sign-in lockout apply to it. --tls and --expose cloudflare-tunnel set TRUST_PROXY to the fixed address of Caddy / cloudflared on the dedicated edge network; --expose proxy needs --trust-proxy (the installer prints the address of a proxy on the same server). The Teleport application agent reaching Tenantry is such a proxy: give its address (its container on the Teleport Docker network, or the host gateway).

Security details of the JWT check: Security.