SELF-HOST · SSO AND HARDENING
Sign in your way. Lock it down.
Connect your own OpenID Connect provider for single sign-on, then follow a short hardening list: private inside, HTTPS in front, encrypted disks and logs you control.
OpenID Connect · Matches by verified email · Passwords keep working
Single sign-on
What it does, and what it does not.
Another way in
It signs in people who already have an account on this install. It never creates one, so someone your provider vouches for but who has no account here is refused.
Matched by email
It matches by email address, and only when the provider says the address is verified.
Nobody locked out
Two-step rules are unchanged, and passwords keep working. Turning single sign-on on does not lock anyone out.
Set it up
Four settings and a restart.
At your provider make a client for Docustay with the sign-in redirect address set to your address plus /api/auth/oidc/callback.
DOCUSTAY_OIDC_ISSUER=https://sso.example.com/realms/main
DOCUSTAY_OIDC_CLIENT_ID=docustay
DOCUSTAY_OIDC_CLIENT_SECRET=<the client secret>
DOCUSTAY_OIDC_LABEL=Example SSOA button named after your label appears on the sign-in page. The public address you set must be the one people use, because the provider sends them back to it.
If it does not work
Three things people hit first.
| What you see | Why | What to do |
|---|---|---|
| No email in the token | The provider keeps the email in its userinfo answer | Include the email scope |
| Provider does not vouch for the email | email_verified is not true | Turn on email verification at the provider |
| A button does not appear | The settings were not picked up | Recreate app, worker and web, then read the app log for lines that start oidc |
Every setting
Five variables, three of them required.
| Variable | Needed | What it is |
|---|---|---|
| DOCUSTAY_OIDC_ISSUER | Yes | The address of your provider, for example a realm on your own identity server |
| DOCUSTAY_OIDC_CLIENT_ID | Yes | The client id you made for Docustay |
| DOCUSTAY_OIDC_CLIENT_SECRET | Yes | The client secret; keep it as private as the other secrets in the settings file |
| DOCUSTAY_OIDC_LABEL | No | The name on the button, by default your identity provider |
| DOCUSTAY_OIDC_SCOPES | No | By default openid email profile; it must include openid and email |
How a sign-in is checked
A standard flow, checked end to end.
The sign-in uses the authorization-code flow with PKCE, a state value and a nonce. The identity token is verified for its signature, issuer, audience, nonce and expiry, and a short-lived cookie holds the state between your click and the provider's reply.
Single sign-on turns on only when the issuer, client id and client secret are all set. It is for self-hosted installs with the built-in identity, and invited people only: an unknown email is refused.
Hardening
Seven parts of a hardening list.
1 / 6
Security settings
Set the workspace's own security settings, including whether an owner requires two-step sign-in for the whole team.
2 / 6
Keep the inside private
Only the web container listens. The database, file store and converter talk on Compose's private network.
3 / 6
Encrypt what is stored
Put the volumes on an encrypted disk, keep the master key safe, and encrypt each backup before it leaves the machine.
4 / 6
Choose your providers
Your own mail, your own sign-in and, if documents must not leave your servers, no AI key at all.
5 / 6
Sign-in and sessions
Offer two-step to everyone, and list or end any session under Settings, Security.
6 / 6
Logs and monitoring
Logs leave out email addresses and credentials; send them to a store you control and set an alert address.
At the edge
HTTPS in front, one port out.
- ProxyPut HTTPS in front with Caddy, nginx or Traefik
- AddressSet the public address to the https address
- FirewallAllow 443, and 80 for the certificate check; nothing else from outside
- PortsDo not publish the database or the file store
- TelemetrySwitch the one anonymous ping off if you must
- UpdatesDo not skip upgrades: release notes say when a fix is about security
Questions
Quick answers.
Does single sign-on create accounts?
No. It only signs in people who already have an account on the install, so invite them first.
Can I use passkeys?
Yes, once you turn them on with the passkey settings in your environment file.
Does the install call out to AI?
Only if you set an AI key. Leave it empty if documents must not leave your servers for drafting.
Where do I read the whole list?
In the hardening guide and the single sign-on guide in the documentation.
Do people need a password if they use single sign-on?
No, because it replaces the password step, but passwords keep working for anyone who has one, so turning single sign-on on locks nobody out. Two-step rules are unchanged.
Which providers work?
Any provider that speaks OpenID Connect with the authorization-code flow and PKCE, such as a Keycloak realm. Register the redirect address that ends in the callback path and give the client id and secret to the install.
Is single sign-on on the hosted service?
No. Single sign-on is for self-hosted installs with the built-in identity, where you run your own provider and your own settings.
What do the logs contain?
Server and worker logs leave out email addresses and credentials. Keep that on, send the logs to a store you control and keep them as long as your policy says.