Gated apps
A deployment has two access settings, and they are independent. access is
whether the SSO gate stands in front of it: gated sends a browser to the
tenant’s Keycloak login and lets only a user holding the deployment’s role
through; open leaves the app’s own login as the only door. exposure is
how far it reaches: lan, the default, or internet. shc ls --posture
adds both columns.
$ shc ls --postureSTACK TENANT ENV APP STATUS NODE ACCESS EXPOSUREcloud prod prod nextcloud running home01 open by default lan by defaultdb prod prod postgres running home01 open by default lan by defaultpgweb prod prod /root/learn/pgweb running home01 open by default lan by defaultplaced prod prod notes running home01 open by default lan by defaultstore prod prod /root/learn/versitygw running home01 open by default lan by defaultweb prod prod /root/learn/nginx running home01 open by default lan by defaultdb prod staging postgres running home01 open by default lan by defaultThe gate works on a hostname route, because it answers at the edge where
Traefik routes by hostname. Giving web a hostname and gating it is one
update. The login page is Keycloak’s, though, and Keycloak answers under the
cluster’s serving host, the name shc init --ingress-host gives a cluster.
This ladder’s shc init named none, so the cluster has no login page to
send a browser to yet. A gate put up now would answer a 502, so the update
is refused and nothing changes.
$ shc cluster host show$ shc update web --expose web.learn.test=nginx:80 --gatedshc: [X409913GATHST] refusing to gate web, the cluster has no serving host for the SSO login to start under, so a browser would get 502; set one with shc cluster host set <host>, nothing was changedshc cluster host set names the host on a running cluster. home01 is a
name this node resolves by itself; a real cluster names a domain its DNS
serves.
$ shc cluster host set home01 --yesNEW CHANGEDhome01 true$ shc cluster host showHOSThome01The system apps move under the new host by themselves: Traefik within a minute, then Keycloak, which restarts once, then OpenObserve. All of it takes about five minutes, and nothing below waits for it but the login.
The same update now goes through. web.learn.test is not in any DNS, so
the curl commands below tell curl where it is. -f makes curl exit non-zero
on an error status, so a gate that could not start the login would fail the
step.
$ shc update web --expose web.learn.test=nginx:80 --gatedupdating deployment "web"...If Keycloak is still in its restart, shc ls --posture reads it
starting. Run it again until every row reads running.
$ shc ls --postureSTACK TENANT ENV APP STATUS NODE ACCESS EXPOSUREcloud prod prod nextcloud running home01 open by default lan by defaultdb prod prod postgres running home01 open by default lan by defaultpgweb prod prod /root/learn/pgweb running home01 open by default lan by defaultplaced prod prod notes running home01 open by default lan by defaultstore prod prod /root/learn/versitygw running home01 open by default lan by defaultweb prod prod /root/learn/nginx running home01 gated lan by defaultdb prod staging postgres running home01 open by default lan by defaultA browser without a session is sent to the login page: a 302. A request that does not ask for HTML gets a 401, because a stylesheet or an API call cannot walk through a login form.
$ curl -skf -o /dev/null -w '%{http_code}' --resolve web.learn.test:443:127.0.0.1 -H 'Accept: text/html' https://web.learn.test/302$ curl -sk -o /dev/null -w '%{http_code}' --resolve web.learn.test:443:127.0.0.1 https://web.learn.test/401shc ingress ls lists the routers Traefik holds. The gated route carries
the shc-oidc middleware, which is the gate.
$ shc ingress ls...A logged-in user gets a 200 through the gate: the gate passes a request
that carries a Keycloak session or a bearer token, and asks SHC whether that
user holds stack:web, the deployment’s own role from the user page. shc auth token prints the bearer of the session shc auth login opened on
this machine and nothing else, so a curl can carry it. On the node no login
was made yet: root reaches the daemon over its socket as a platform admin,
which is no Keycloak session, so the command refuses.
$ shc auth token --tenant prodshc: [X401903NOSESS] not logged in to tenant prod: no active cluster, run `shc auth login --tenant prod`A login without a browser is a service client, the automation client from
the user page. shc auth create-service-client prints its secret once;
with --fields client_secret -o text it prints the secret alone, into a
pipe to the client-credentials login, whose --client-secret - reads it,
so the secret is never shown or copied. shc auth token from then on
prints the bearer the login stored. The client lives in the master realm,
so every token it gets is platform root, and the gate lets a platform admin
through without asking for stack:web; a tenant user’s bearer is judged on
that role instead. curl reads the bearer itself with $(shc auth token),
the one command it needs, so the bearer is never copied.
The login asks Keycloak under the cluster’s host, and Keycloak is still restarting to move there. This is the wait: curl exits non-zero until the answer is a 200.
$ curl -skf -o /dev/null -w '%{http_code}' https://home01/auth/realms/master/.well-known/openid-configuration200--url names the host SHC serves its API on, the one set above. The first
login to a cluster pins its CA and prints the fingerprint. The login makes
that cluster the active context, so the CLI on this node talks to it over
the API with the bearer until shc auth logout and shc ctx --reset put
the socket back. The reset drops the tenant too, so shc ctx -t prod
selects it again.
$ shc auth create-service-client learn --fields client_secret -o text | shc auth login --url https://home01 --client-credentials --client-id learn --client-secret -warning: store the secret now: it is shown only this once and can be re-minted with --rotate-secret...✔ logged in to "https://home01" in realm "master" with client credentials; cluster "home01" is now active$ shc auth token<redacted>$ curl -skf -o /dev/null -w '%{http_code}' --resolve web.learn.test:443:127.0.0.1 -H 'Accept: text/html' -H "Authorization: Bearer $(shc auth token)" https://web.learn.test/200$ shc auth logout✔ logged out of cluster "home01" locally, stored tokens cleared, but the IdP session was not ended: no refresh token stored, nothing to end at the IdP Any access token already issued stays valid until it expires: a logout cannot recall one. To cut access off now, revoke the session at the IdP: an operator can end it in the Keycloak admin console, and back-channel logout then propagates it to every app.$ shc ctx --resetCLUSTER ENDPOINT DEV DEBUG VERBOSEunix:/run/shc/shc.sock unix:/run/shc/shc.sock false false false...$ shc ctx -t prod...--gated and --open are the two values of one setting, so naming both is
refused before the command runs. Open the deployment again and the same
request gets the page.
$ shc update web --gated --open$ shc update web --openupdating deployment "web"...$ curl -skf -o /dev/null -w '%{http_code}' --resolve web.learn.test:443:127.0.0.1 -H 'Accept: text/html' https://web.learn.test/200The route lost the middleware on the sweep that followed the update.
$ shc ingress ls...Exposure is the other setting. --public raises a deployment to the
internet; --private walks it back to the LAN.
$ shc update web --publicupdating deployment "web"...$ shc ls --postureSTACK TENANT ENV APP STATUS NODE ACCESS EXPOSUREcloud prod prod nextcloud running home01 open by default lan by defaultdb prod prod postgres running home01 open by default lan by defaultpgweb prod prod /root/learn/pgweb running home01 open by default lan by defaultplaced prod prod notes running home01 open by default lan by defaultstore prod prod /root/learn/versitygw running home01 open by default lan by defaultweb prod prod /root/learn/nginx running home01 open internetdb prod staging postgres running home01 open by default lan by default$ shc update web --privateupdating deployment "web"...$ shc ls --postureSTACK TENANT ENV APP STATUS NODE ACCESS EXPOSUREcloud prod prod nextcloud running home01 open by default lan by defaultdb prod prod postgres running home01 open by default lan by defaultpgweb prod prod /root/learn/pgweb running home01 open by default lan by defaultplaced prod prod notes running home01 open by default lan by defaultstore prod prod /root/learn/versitygw running home01 open by default lan by defaultweb prod prod /root/learn/nginx running home01 open landb prod staging postgres running home01 open by default lan by defaultAn app can ask for the gate itself. access: gated in its app.yaml makes
every install of it gated unless the install says --open. The gate
covers the whole app: an app that needs open paths ships public and guards
itself, and ungated_paths is kept for two carve-outs in the catalogue,
docuseal’s /s/ signing links and paperless /accounts/login. self_auth: false
says the app has no login of its own, so SHC warns if it is ever published
open. Make a gated copy of the nginx app on home01.
name: gatedversion: "1.0.0"title: Gated pagedescription: nginx behind the SSO gatecategory: weblicense: id: MITaccess: gatedself_auth: falseservices: nginx: image: nginx:1.27-alpine expose: - "80" volumes: - ./site:/usr/share/nginx/html:ro<!doctype html><title>gated</title><p>Only for people who signed in.</p>$ shc install ~/learn/gated -s gate --expose gate.learn.test=nginx:80installing deployment "gate"[gate] Healthy 1/1✔ nginx healthy✔ installed deployment "gate"exposure: lan$ shc ls --postureSTACK TENANT ENV APP STATUS NODE ACCESS EXPOSUREcloud prod prod nextcloud running home01 open by default lan by defaultdb prod prod postgres running home01 open by default lan by defaultgate prod prod /root/learn/gated running home01 gated by default lan by defaultpgweb prod prod /root/learn/pgweb running home01 open by default lan by defaultplaced prod prod notes running home01 open by default lan by defaultstore prod prod /root/learn/versitygw running home01 open by default lan by defaultweb prod prod /root/learn/nginx running home01 open landb prod staging postgres running home01 open by default lan by default$ curl -skf -o /dev/null -w '%{http_code}' --resolve gate.learn.test:443:127.0.0.1 -H 'Accept: text/html' https://gate.learn.test/302Three more app.yaml keys belong to an app with a sign-in page of its own,
which that one has not. The next app has one: a form at /login.html and,
beside it, the address its sign-in-with-SSO button opens, /sso/start.html.
A real app starts its own login with the identity provider there. Here both
are static pages, which is all the three keys read.
sso_redirect names the pair, so SHC can send a browser that asks for the
form straight to the SSO start. local_login names the variable that takes
the app’s own form away, so SHC can tell after a restore that nobody can
sign in. ungated_npm_metadata is for an app that serves an npm registry
behind the gate: the metadata of the packages it names stays readable
without a session, which is what a package manager asks for before it has
one.
name: doorversion: "1.0.0"title: Doordescription: nginx with a sign-in page of its owncategory: weblicense: id: MITvars: ssoOnly@bool: whether the sign-in form is taken awaysso_redirect: login_path: "{{ path('nginx') }}/login.html" sso_start: "{{ url('nginx') }}/sso/start.html"local_login: closed_by: [ssoOnly] gated_on_edge: falseungated_npm_metadata: - service: nginx distribution_path: /pulp/content/npm/ scope: learn packages: [door]ssoOnly: falseservices: nginx: image: nginx:1.27-alpine expose: - "80" volumes: - ./site:/usr/share/nginx/html:ro - ./default.conf:/etc/nginx/conf.d/default.conf:roA registry answers a package’s metadata under one path. This nginx stands
in for one: it answers every path under /pulp/content/npm/ itself, so
below only the gate decides who gets an answer.
server { listen 80; root /usr/share/nginx/html; index index.html; location /pulp/content/npm/ { default_type application/json; return 200 '{"served": "by nginx"}'; }}<!doctype html><title>door</title><p>Inside.</p><!doctype html><title>sign in</title><form><input name="user"><input name="password" type="password"></form><a href="/sso/start.html">Sign in with SSO</a><!doctype html><title>sso</title><p>A real app sends the browser to its identity provider from here.</p>Install it open. A browser that asks for the form gets the form: the app declares where its SSO starts, and whether to send people there is the operator’s choice, off until it is made.
$ shc install ~/learn/door -s door --expose door.learn.test=nginx:80installing deployment "door"[door] Healthy 1/1✔ nginx healthy✔ installed deployment "door"exposure: lan$ curl -skf -o /dev/null -w '%{http_code}' --resolve door.learn.test:443:127.0.0.1 -H 'Accept: text/html' https://door.learn.test/login.html200The choice is the config key ssoAutoRedirect, set here for the tenant
prod, where door is the only app that declares a redirect. -t prod
narrows the row to that tenant, and --scope tenant says so outright. A row
set with --scope global would reach every tenant’s apps, and they would
all start sending people on. Within a
minute, the next sweep, a browser that asks for the form is sent to the SSO
start on the same host. Two requests still get the form: one that carries
?sso=false, the way back to the app’s own form when the identity provider
is down, and one that does not ask for HTML.
$ shc config set ssoAutoRedirect true --scope tenant -t prodKEY VALUE SCOPEssoAutoRedirect true tenant$ curl -sk -o /dev/null -w '%{http_code} %{redirect_url}' --resolve door.learn.test:443:127.0.0.1 -H 'Accept: text/html' https://door.learn.test/login.html302 https://door.learn.test/sso/start.html$ curl -skf -o /dev/null -w '%{http_code}' --resolve door.learn.test:443:127.0.0.1 -H 'Accept: text/html' 'https://door.learn.test/login.html?sso=false'200$ curl -skf -o /dev/null -w '%{http_code}' --resolve door.learn.test:443:127.0.0.1 https://door.learn.test/login.html200Now put the gate in front of door. Everything on the host asks for a
session, except the metadata of the one package the app named. door in
the scope learn answers, spelled plainly or encoded the way a package
manager sends it, and other beside it does not.
$ shc update door --gatedupdating deployment "door"...$ curl -sk -o /dev/null -w '%{http_code}' --resolve door.learn.test:443:127.0.0.1 https://door.learn.test/401$ curl -skf -o /dev/null -w '%{http_code}' --resolve door.learn.test:443:127.0.0.1 https://door.learn.test/pulp/content/npm/@learn/door200$ curl -skf -o /dev/null -w '%{http_code}' --resolve door.learn.test:443:127.0.0.1 https://door.learn.test/pulp/content/npm/%40learn%2Fdoor200$ curl -sk -o /dev/null -w '%{http_code}' --resolve door.learn.test:443:127.0.0.1 https://door.learn.test/pulp/content/npm/@learn/other401local_login matters after a restore. Turn ssoOnly on, which in a real
app takes the form away, back the deployment up and restore it. door has
no identity provider bound, so the restored deployment has no form and no
SSO: it would answer 200 and let nobody in. SHC cannot fix that for you,
but it says so, with the command that opens the form again.
$ shc update door --var ssoOnly=trueupdating deployment "door"...effective config delta: changed: ssoOnly...$ shc backup create door --name closed[door] Complete 3/3✔ validate the request✔ back up✔ record the backup✔ created backup "20261106T181910Z_6b13d88590a5cf2b" named "closed"$ shc backup restore closed -s door --yes✔ restored backup "20261106T181910Z_6b13d88590a5cf2b" into stack "door" in environment prod; pre-restore safety backup "20261106T181921Z_5d66ab657667c12e"$ journalctl --no-pager -u shc --since '10 min ago' -o cat -g X200042NOLOGIN -n 1time=2026-10-10T00:07:44.527Z level=WARN msg="restored deployment door has NO usable login path, ssoOnly is on so its credential login form is not rendered and none of its 0 identity edges is reachable, the deployment answers 200 while offering nobody a way in including admins, reopen the local door with shc update door --var ssoOnly=false, or bring the recorded IdP back and re-render" code=X200042NOLOGIN http_status=200 closed_by=ssoOnly edges="0 identity edges" stack=door tenant=prod stack=doorOpen the form again as the warning says, take the config row away and
remove door.
$ shc update door --var ssoOnly=falseupdating deployment "door"...effective config delta: changed: ssoOnly...$ shc config unset ssoAutoRedirect --scope tenant -t prodKEY SCOPE REMOVEDssoAutoRedirect tenant true$ shc uninstall door --yesuninstalling deployment "door"[door] Complete 4/4✔ remove from home01✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ uninstalled deployment "door"The gate, and the launcher, the app switcher SHC injects into the pages of a gated app, are tuned by cluster config keys. Read the ones this page leaned on; each is at its default here.
$ shc config get ssoAutoRedirect...$ shc config get launcher...$ shc config get lanEnforcement...$ shc config get auth.gate_cookie_domain...$ shc config get keycloak.access_token_lifespan...Put your own LAN’s range in lanAllowlistCidrs; 192.0.2.0/24 stands in for
it below.
$ shc config set ssoAutoRedirect true --scope global$ shc config set launcher false --scope global$ shc config set launcherGzip false --scope global$ shc config set launcherPlaced false --scope global$ shc config set launcherEnvironment all --scope global$ shc config set lanEnforcement off --scope global$ shc config set lanAllowlistCidrs 192.0.2.0/24 --scope global$ shc config set auth.gate_cookie_domain estate --scope global$ shc config set auth.platform_admins prod/3f0e9a52-7c1d-4e8b-9a61-2b5c8d4e7f10 --scope global$ shc config set keycloak.access_token_lifespan 3600 --scope global$ shc config set keycloak.sso_session_idle_timeout 900 --scope global$ shc config set keycloak.sso_session_max_lifespan 36000 --scope global$ shc config set keycloak.offline_session_idle_timeout 604800 --scope global$ shc config set keycloak.policy_cache_ttl 30 --scope global$ shc config set keycloak.login_theme shc-springboard --scope global$ shc config set keycloak.remember_me false --scope global$ shc config set keycloak.admin_events_enabled false --scope global$ shc config set keycloak.admin_events_details_enabled true --scope global$ shc config set keycloak.tls_verify false --scope global$ shc config get keycloak.client_id$ shc config get keycloak.base_path$ shc config get keycloak.realm$ shc config get portal.enabled$ shc config get portal.url$ shc config get portal.require_requested_installsThe same install with --open would have left the gate off, and --gated
on an app that says nothing turns it on.
$ shc install ~/learn/gated -s gate --expose gate.learn.test=nginx:80 --open$ shc install ~/learn/nginx -s gate --expose gate.learn.test=nginx:80 --gatedRemove gate and take the hostname off web; a trailing ! removes a
route.
$ shc uninstall gate --yesuninstalling deployment "gate"[gate] Complete 4/4✔ remove from home01✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ uninstalled deployment "gate"$ shc update web --expose web.learn.test!updating deployment "web"...$ shc ls --postureSTACK TENANT ENV APP STATUS NODE ACCESS EXPOSUREcloud prod prod nextcloud running home01 open by default lan by defaultdb prod prod postgres running home01 open by default lan by defaultpgweb prod prod /root/learn/pgweb running home01 open by default lan by defaultplaced prod prod notes running home01 open by default lan by defaultstore prod prod /root/learn/versitygw running home01 open by default lan by defaultweb prod prod /root/learn/nginx running home01 open landb prod staging postgres running home01 open by default lan by defaultweb is open and LAN-only again, on its port from the first app page; its
row now says so outright instead of by default. The other deployments are
as the last page left them.
Next: Connections.