Skip to content
SHC Docs

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.

home01
$ shc ls --posture
STACK TENANT ENV APP STATUS NODE ACCESS EXPOSURE
cloud prod prod nextcloud running home01 open by default lan by default
db prod prod postgres running home01 open by default lan by default
pgweb prod prod /root/learn/pgweb running home01 open by default lan by default
placed prod prod notes running home01 open by default lan by default
store prod prod /root/learn/versitygw running home01 open by default lan by default
web prod prod /root/learn/nginx running home01 open by default lan by default
db prod staging postgres running home01 open by default lan by default

The 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.

home01
$ shc cluster host show
$ shc update web --expose web.learn.test=nginx:80 --gated
shc: [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 changed

shc 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.

home01
$ shc cluster host set home01 --yes
NEW CHANGED
home01 true
$ shc cluster host show
HOST
home01

The 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.

home01
$ shc update web --expose web.learn.test=nginx:80 --gated
updating deployment "web"
...

If Keycloak is still in its restart, shc ls --posture reads it starting. Run it again until every row reads running.

home01
$ shc ls --posture
STACK TENANT ENV APP STATUS NODE ACCESS EXPOSURE
cloud prod prod nextcloud running home01 open by default lan by default
db prod prod postgres running home01 open by default lan by default
pgweb prod prod /root/learn/pgweb running home01 open by default lan by default
placed prod prod notes running home01 open by default lan by default
store prod prod /root/learn/versitygw running home01 open by default lan by default
web prod prod /root/learn/nginx running home01 gated lan by default
db prod staging postgres running home01 open by default lan by default

A 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.

home01
$ 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/
401

shc ingress ls lists the routers Traefik holds. The gated route carries the shc-oidc middleware, which is the gate.

home01
$ 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.

home01
$ shc auth token --tenant prod
shc: [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.

home01
$ curl -skf -o /dev/null -w '%{http_code}' https://home01/auth/realms/master/.well-known/openid-configuration
200

--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.

home01
$ 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 --reset
CLUSTER ENDPOINT DEV DEBUG VERBOSE
unix:/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.

explained, not walked: the flag parser refuses the pair before shc runs, with no error code a walk can promise
$ shc update web --gated --open
home01
$ shc update web --open
updating deployment "web"
...
home01
$ 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/
200

The route lost the middleware on the sweep that followed the update.

home01
$ shc ingress ls
...

Exposure is the other setting. --public raises a deployment to the internet; --private walks it back to the LAN.

home01
$ shc update web --public
updating deployment "web"
...
$ shc ls --posture
STACK TENANT ENV APP STATUS NODE ACCESS EXPOSURE
cloud prod prod nextcloud running home01 open by default lan by default
db prod prod postgres running home01 open by default lan by default
pgweb prod prod /root/learn/pgweb running home01 open by default lan by default
placed prod prod notes running home01 open by default lan by default
store prod prod /root/learn/versitygw running home01 open by default lan by default
web prod prod /root/learn/nginx running home01 open internet
db prod staging postgres running home01 open by default lan by default
$ shc update web --private
updating deployment "web"
...
$ shc ls --posture
STACK TENANT ENV APP STATUS NODE ACCESS EXPOSURE
cloud prod prod nextcloud running home01 open by default lan by default
db prod prod postgres running home01 open by default lan by default
pgweb prod prod /root/learn/pgweb running home01 open by default lan by default
placed prod prod notes running home01 open by default lan by default
store prod prod /root/learn/versitygw running home01 open by default lan by default
web prod prod /root/learn/nginx running home01 open lan
db prod staging postgres running home01 open by default lan by default

An 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.

~/learn/gated/app.yaml
name: gated
version: "1.0.0"
title: Gated page
description: nginx behind the SSO gate
category: web
license:
id: MIT
access: gated
self_auth: false
~/learn/gated/compose.yaml
services:
nginx:
image: nginx:1.27-alpine
expose:
- "80"
volumes:
- ./site:/usr/share/nginx/html:ro
~/learn/gated/site/index.html
<!doctype html>
<title>gated</title>
<p>Only for people who signed in.</p>
home01
$ shc install ~/learn/gated -s gate --expose gate.learn.test=nginx:80
installing deployment "gate"
[gate] Healthy 1/1
✔ nginx healthy
✔ installed deployment "gate"
exposure: lan
$ shc ls --posture
STACK TENANT ENV APP STATUS NODE ACCESS EXPOSURE
cloud prod prod nextcloud running home01 open by default lan by default
db prod prod postgres running home01 open by default lan by default
gate prod prod /root/learn/gated running home01 gated by default lan by default
pgweb prod prod /root/learn/pgweb running home01 open by default lan by default
placed prod prod notes running home01 open by default lan by default
store prod prod /root/learn/versitygw running home01 open by default lan by default
web prod prod /root/learn/nginx running home01 open lan
db prod staging postgres running home01 open by default lan by default
home01
$ 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/
302

Three 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.

~/learn/door/app.yaml
name: door
version: "1.0.0"
title: Door
description: nginx with a sign-in page of its own
category: web
license:
id: MIT
vars:
ssoOnly@bool: whether the sign-in form is taken away
sso_redirect:
login_path: "{{ path('nginx') }}/login.html"
sso_start: "{{ url('nginx') }}/sso/start.html"
local_login:
closed_by: [ssoOnly]
gated_on_edge: false
ungated_npm_metadata:
- service: nginx
distribution_path: /pulp/content/npm/
scope: learn
packages: [door]
~/learn/door/vars.yaml
ssoOnly: false
~/learn/door/compose.yaml
services:
nginx:
image: nginx:1.27-alpine
expose:
- "80"
volumes:
- ./site:/usr/share/nginx/html:ro
- ./default.conf:/etc/nginx/conf.d/default.conf:ro

A 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.

~/learn/door/default.conf
server {
listen 80;
root /usr/share/nginx/html;
index index.html;
location /pulp/content/npm/ {
default_type application/json;
return 200 '{"served": "by nginx"}';
}
}
~/learn/door/site/index.html
<!doctype html>
<title>door</title>
<p>Inside.</p>
~/learn/door/site/login.html
<!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>
~/learn/door/site/sso/start.html
<!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.

home01
$ shc install ~/learn/door -s door --expose door.learn.test=nginx:80
installing deployment "door"
[door] Healthy 1/1
✔ nginx healthy
✔ installed deployment "door"
exposure: lan
home01
$ 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
200

The 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.

home01
$ shc config set ssoAutoRedirect true --scope tenant -t prod
KEY VALUE SCOPE
ssoAutoRedirect true tenant
home01
$ 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.html
302 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.html
200

Now 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.

home01
$ shc update door --gated
updating deployment "door"
...
home01
$ 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/door
200
$ 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%2Fdoor
200
$ 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/other
401

local_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.

home01
$ shc update door --var ssoOnly=true
updating 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"
home01
$ journalctl --no-pager -u shc --since '10 min ago' -o cat -g X200042NOLOGIN -n 1
time=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=door

Open the form again as the warning says, take the config row away and remove door.

home01
$ shc update door --var ssoOnly=false
updating deployment "door"
...
effective config delta: changed: ssoOnly
...
$ shc config unset ssoAutoRedirect --scope tenant -t prod
KEY SCOPE REMOVED
ssoAutoRedirect tenant true
$ shc uninstall door --yes
uninstalling 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.

home01
$ 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.

explained, not walked: each of these changes how every gated app on the cluster behaves, and the walk keeps the defaults it read above; the values here are the other settings
$ 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_installs

The same install with --open would have left the gate off, and --gated on an app that says nothing turns it on.

explained, not walked: the same two flags as on update, and the walk has shown both settings already
$ 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 --gated

Remove gate and take the hostname off web; a trailing ! removes a route.

home01
$ shc uninstall gate --yes
uninstalling 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 --posture
STACK TENANT ENV APP STATUS NODE ACCESS EXPOSURE
cloud prod prod nextcloud running home01 open by default lan by default
db prod prod postgres running home01 open by default lan by default
pgweb prod prod /root/learn/pgweb running home01 open by default lan by default
placed prod prod notes running home01 open by default lan by default
store prod prod /root/learn/versitygw running home01 open by default lan by default
web prod prod /root/learn/nginx running home01 open lan
db prod staging postgres running home01 open by default lan by default

web 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.