Documentation for v2.7.0. Read the latest, v2.12.0.

Operator

Authentication

Humans sign in with a password, through the directory or through an OpenID Connect provider; builds and scripts always use an API token. This chapter is the human side: how a login is checked, where the accounts come from, and what keeps an operator from locking themselves out.

Authentication modes#

The mode is a setting (auth_mode), chosen in the Authentication section of /admin.html or with PUT /admin/auth-config (manage_auth_config). The first start sets local.

PUT /admin/auth-config accepts off and maintenance as spellings of disabled; any other mode answers 400 Invalid auth mode: …. ldap without an ldap_config in the same request answers LDAP config required for ldap mode; oidc without an oidc_config stored or supplied answers OIDC config required for oidc mode. Every change is an UPDATE_SETTINGS audit entry.

Administrative routes (/admin/*) take a session token from POST /auth/login; an API token on them answers 401. The one exception is the backup download, which admits a full API token. A session lasts 7 days.

Local accounts#

Anyone can register on the Register tab of the sign-in page or with POST /auth/register ({"username","password"}); there is no switch that closes registration. A new account is pending until an administrator approves it (approval): the Users section of the admin page, or POST /admin/users/{id}/approve (manage_users). A pending user's login answers 403; a wrong password 401, and so does an empty one, refused before any check. The Auto Acknowledge New Users toggle (auto_approve_users) approves new registrations at once; it is off by default and meant for a lab, not for a company. In the Users list every account carries its badges: one per role it holds directly (admin, viewer, …), and approved or pending.

Registration refuses a name twice: 409 User already exists, and 409 This username is reserved for every name in SANSHAIN_ROOT_USERS that has no account yet (startup creates a locked one, see Root users). Deleting a user (DELETE /admin/users/{id}) revokes their sessions and API tokens. Users change their own password on /account.html; there is no administrative password reset.

The initial admin and root#

On the first start, with no user in the database, Sanshain creates INITIAL_ADMIN_USERNAME (root) with INITIAL_ADMIN_PASSWORD or a random password, grants it the admin role and prints both lines to stderr:

[INITIAL SETUP] Admin user created. Username: root, Password: <random>
[INITIAL SETUP] Change this password immediately at https://sanshain.corp/admin.html

The second line names the admin page under PUBLIC_BASE_URL; without it, under the bind address (http://0.0.0.0:3000/admin.html by default). A set but empty INITIAL_ADMIN_PASSWORD counts as unset, and an empty password is never accepted at login.

That account is also root by the default of SANSHAIN_ROOT_USERS: every permission, including ones no role grants, from configuration rather than from the database. Name a second account there as the break-glass path; the full rules are in Configuration.

LDAP and Active Directory#

Select LDAP in the Authentication section and fill the form:

Test Connection (POST /admin/auth-config/test with the form's fields) connects and binds with the service account; Save Authentication Settings applies. The same through the API:

curl -X PUT $SANSHAIN/admin/auth-config \
  -H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" \
  -d '{
    "auth_mode": "ldap",
    "ldap_config": {
      "server_url": "ldaps://ldap.example.com:636",
      "bind_dn": "cn=readonly,dc=example,dc=com",
      "bind_password": "secret",
      "base_dn": "dc=example,dc=com",
      "user_filter": "(uid={username})",
      "admin_group": "cn=admins,ou=groups,dc=example,dc=com",
      "use_tls": false
    }
  }'

GET /admin/auth-config returns the mode and the configuration with the password redacted.

How a login is checked#

1. A TCP connection to the host and port, with a 5 s limit: Could not connect to LDAP server at …: no answer within 5 s when nothing answers.
2. The TLS or StartTLS handshake and the service-account bind, each under the operation timeout (10 s, LDAP_OPERATION_TIMEOUT_SECS).
3. A subtree search under the Base DN with the User Filter, reading dn and memberOf.
4. A second connection binding as the found DN with the given password.
5. On success a shadow account with that username is created in the local database (approved, random local password), so sessions, favourites and API tokens work as for a local user. No group or role is captured at login.

What the user may do is decided on every authorisation check: their memberOf groups are read through the service account, cached for SANSHAIN_DIRECTORY_GROUP_TTL_SECS (300), and matched against the directory groups in the group mapping; the roles attached to matching groups apply. A promotion or demotion in the directory takes effect within the cache TTL, without a new login. When the directory is unreachable, directory roles are omitted (see Directory group caching). Password login falls back to the local check when the directory refuses or fails, so root and local accounts are never locked out by the directory.

Timeouts, schemes and ports#

The connect timeout cannot help once the port answers. A scheme and port mismatch, or a firewall that accepts and then drops, used to hang the request until the ingress gave up with 502 Bad Gateway. Since 2.6.0 every exchange after the connect runs under the operation timeout. Test Connection answers 400 with:

LDAP connection failed: Connection failed: LDAP server at ldaps://ldap.example.com:389 accepted the connection but did not respond within 10 s. Check that ldaps:// uses the TLS port and StartTLS the plain one.

Only Test Connection shows the text. A login that hits the same stall is treated like any directory refusal: the local password check runs and the caller gets a bare 401.

Keep the ingress timeout above the operation timeout so Sanshain's message, not the proxy's, reaches the admin page.

Certificates#

ldaps:// and StartTLS verify the directory's certificate. The image trusts the public authorities; a private or corporate CA is mounted and named by EXTRA_CA_CERTS_DIR, see Additional CA certificates. Without it, Test Connection fails on certificate verification.

OpenID Connect#

OIDC is for people. It is configured through the API only; the admin page has no OIDC form in 2.6.0.

curl -X PUT $SANSHAIN/admin/auth-config \
  -H "Authorization: Bearer $SESSION" -H "Content-Type: application/json" \
  -d '{
    "auth_mode": "oidc",
    "oidc_config": {
      "issuer_url": "https://login.example.com/realms/corp",
      "client_id": "sanshain",
      "client_secret": "…",
      "redirect_url": "https://sanshain.corp/auth/oidc/callback",
      "username_claim": "preferred_username",
      "groups_claim": "groups",
      "admin_group": "sanshain-admins"
    }
  }'

The sign-in page shows Sign in with SSO (GET /auth/oidc/login). The flow is authorization code with PKCE: state, nonce and verifier travel in a 10-minute HttpOnly cookie; the callback (GET /auth/oidc/callback) exchanges the code, verifies the ID token (signature against the provider's JWKS, nonce, issuer, audience, expiry), creates or finds the shadow account (approved) and sets the session cookie, then redirects to /account.html. Without a configuration both routes answer 400 OIDC is not configured; a callback without its cookie answers 400 no OIDC login in progress; a provider that cannot be reached at discovery answers 500 OIDC discovery failed: ….

Developer mode#

Developer mode switches authentication off: API and admin routes act as a built-in dev_user. It needs two things at once:

1. A request: the Dev Mode radio (which stores dev_mode=true) or SANSHAIN_DEV_MODE=true in the environment.
2. The gate: ALLOW_INSECURE_DEV_MODE=true in the environment.

A request without the gate fails closed: authentication stays enforced and startup logs

SECURITY: dev_mode is requested but the ALLOW_INSECURE_DEV_MODE safety gate is not set to 'true'. Refusing to enable dev mode - authentication stays enforced.

With both, startup logs SECURITY WARNING: dev_mode is ENABLED - API endpoints accept unauthenticated requests. Disable it in production. The gate belongs on a laptop and nowhere else; a persisted setting left behind by configuration drift cannot open a production instance on its own.

Checked against v2.6.1.