Authentication and Access Control
The StencilBox web UI and API need a login. Built sites in the output directory stay public: anyone who can reach StencilBox can view them.
Users, groups, roles and sessions are stored in a SQLite database, stencilbox.db, next to config.yaml (/config/stencilbox.db in Docker). StencilBox creates the database and applies any schema changes when it starts, so there is no separate migration step. Back the file up with the rest of /config.
Running without a database
StencilBox can also run without a database. It then has no user accounts, and instead trusts whoever is using it from the same computer:
-
Requests made directly from localhost (
127.0.0.1or::1) are signed in aslocalhost. They can do everything except things that need a database: building, editing data files and creating build configs all work. -
Every other request is refused. That includes requests through a reverse proxy (any request with
X-Forwarded-For,X-Real-IP,ForwardedorX-Forwarded-Host), even when the proxy runs on the same computer, because a proxy makes everyone look local. -
Logins, user accounts, groups, roles and API keys are not available. MCP works from localhost, without an API key.
-
Built sites are public as always.
StencilBox runs without a database when:
-
config.yamlhasdatabase: {enabled: false}, or the environment hasSTENCILBOX_DB_DISABLED=true, or -
the database cannot be opened, for example because the config directory is read-only. StencilBox logs an error and carries on without it, rather than not starting.
| In Docker, the browser’s requests reach the container from the Docker network, not from localhost, so without a database they are refused. Use a database in Docker (the default), or run the container with host networking. |
database:
enabled: false
First login
When the database has no users, StencilBox creates one:
-
Username:
admin -
Password:
admin
Log in, click your username in the top right, and change the password. Until you do, the web UI shows a warning to superusers.
If you are locked out, start StencilBox once with STENCILBOX_RESET_ADMIN_PASSWORD=1. This sets the admin password back to admin and puts admin back in the Administrators group. Remove the variable and restart afterwards.
Users, groups, roles and permissions
Access is group based:
-
A permission allows one kind of action, such as
users.createorrbac.manage. The build permissions arebuildconfigs.view(build configs, history, templates and data files),builds.run(start builds and clear caches),datafiles.edit(replace data files, see API and MCP),buildconfigs.manage(create build configs and add data files; superusers only by default) andbuildconfigs.git-pull.app.accesscovers the rest of everyday use. -
A role is a set of permissions.
-
A group has roles. Users get every permission from every role of every group they are in.
Permissions are never given to a user directly. To give someone access, add them to a group that has the role you want.
Two groups and two roles always exist and cannot be deleted:
Name |
Kind |
Purpose |
|
Group |
Every user is a member. Has the |
|
Group |
Has the |
|
Role |
Normal use of StencilBox: |
|
Role |
Every permission, including ones added in later versions. Its permissions cannot be edited. |
StencilBox refuses any change that would leave no user with superuser.
Manage all of this from Control Panel > Identity & Access in the web UI. Each user can see their own groups and permissions under their username > My Permissions.
API keys
Scripts can call the API with an API key instead of a browser session. Create one from your username > API Keys, then send it as a header:
Authorization: Bearer sbk_...
The key is shown once, when it is created.
By default a key can do everything its owner can. When you create a key, or later by clicking it, you can narrow it:
-
Permissions: only the permissions you tick. For example, a key for a CI job that rebuilds a site needs only
builds.run. -
Build configs: only the build configs you tick. Building, clearing caches, and reading configs, history and data files are refused for any other build config, and lists only show the allowed ones.
A key never has more access than its owner has right now. If the owner loses a permission, or is deleted, their keys lose it too.
API keys cannot create, change or delete API keys, or change passwords. Those need a login in the web UI, so a narrow key cannot be used to make a broader one.
curl -X POST https://stencilbox.example.com/api/StencilBox.clientapi.v1.StencilBoxApiService/ClearBuildCache \
-H 'Authorization: Bearer sbk_...' \
-H 'Content-Type: application/json' \
-d '{"configName": "My links homepage"}'
Single sign-on and reverse proxies
The auth block in config.yaml configures httpauthshim. Users signed in this way are still StencilBox users, and still get their access from groups.
- JWT (for example Cloudflare Access, or an OAuth2 proxy that issues JWTs)
-
StencilBox creates the user on their first visit and adds them to
Everyone. Give them more access by adding them to groups.auth: jwt: certsUrl: https://example.cloudflareaccess.com/cdn-cgi/access/certs aud: your-application-audience-tag claimUsername: email header: Cf-Access-Jwt-Assertion - Trusted headers
-
A reverse proxy sets the username in a header. The user must already exist in StencilBox.
auth: httpHeader: username: X-Forwarded-UserOnly use trusted headers when every request reaches StencilBox through the proxy, and the proxy strips this header from incoming requests. Otherwise anyone can set the header and log in as any user. - mTLS
-
Set
auth.mtls.enabled: trueto accept client certificates. See the httpauthshim documentation for the options.
The auth.localUsers option from earlier versions of StencilBox is no longer used. Create those users in the web UI instead.
Session cookies
The login form sets an HttpOnly, SameSite=Strict cookie called stencilbox-sid. The cookie is marked Secure when the request arrived over HTTPS, either directly or through a proxy that sets X-Forwarded-Proto: https.
Environment variables
Variable |
Description |
Default |
|
Path to the SQLite database. |
|
|
|
Unset |
|
|
Decided per request, from the scheme |
|
When set, reset the |
Unset |
|
|
Unset |