Sign-in and identity

Jiandu keeps authentication and authorization separate. A password, passkey, or external provider establishes which local person is signing in; Jiandu then applies that person's local household role, group membership, and document access policy. Provider groups can decide whether a new or returning identity may enter, but they never become Jiandu roles.

That separation has two useful consequences:

• changing identity providers does not rewrite document permissions; and
• compromising a provider-side role claim cannot grant Jiandu Administrator or restricted-document access by itself.

Choose a sign-in method

Method	Choose it when	Important trade-off
Local password	You want the fewest dependencies or a tested fallback	Jiandu owns password recovery and credential policy; no upstream MFA is inherited
Passkey	Members have compatible authenticators and you want phishing-resistant browser sign-in	The HTTPS hostname/RP ID becomes a durable credential boundary; plan recovery before rollout
OIDC	You already operate Authentik, Keycloak, Authelia, or another conforming provider	Recommended external integration, but sign-in depends on provider discovery, TLS, and availability
LDAP or Active Directory	A directory is authoritative but cannot expose OIDC	Jiandu must verify a password against the directory on every sign-in; TLS and immutable attributes are critical
Trusted proxy	An existing access gateway can only assert protected headers	Expert compatibility path; correctness spans peer filtering, a shared secret, and header replacement

Methods can coexist. A practical production baseline is OIDC or passkeys for ordinary use, one tested local Administrator credential, and the Owner recovery token stored separately offline.

Personal access tokens are for scripts and integrations, not browser sign-in. They remain limited by both their scopes and the issuing member's local authorization.

Understand the three identities involved

credential or external subject
            │ proves identity
            ▼
      local Jiandu member
            │ receives local authorization
            ▼
 role + groups + document access policy

The built-in Owner is a separate break-glass principal backed by a high-entropy file token. It is not a household password and should not be used for daily work. The first normal human account claims installation administration; the Owner remains available for recovery.

External identities use durable keys:

• OIDC: configured provider ID plus the verified (issuer, subject) pair;
• LDAP/AD: configured provider ID plus one immutable directory attribute; and
• trusted proxy: configured provider ID plus the asserted immutable subject.

Email addresses, display names, usernames, and group labels can change and are not automatic linking keys. Linking an external identity to an existing member is an explicit, recent-sign-in operation. One external identity cannot silently merge two local accounts.

Choose an admission policy

Admission controls what happens the first time an unknown external identity signs in. It does not change an existing member's Jiandu role.

Policy	Available for	Behavior	Recommended use
invitation_only	OIDC, LDAP, trusted proxy	Unknown identity must present a matching, unexpired, one-use Jiandu invitation	Default; households and tightly managed deployments
required_group	OIDC, LDAP, trusted proxy	One configured provider claim/attribute/header must contain an exact configured value	Managed directory group that is reviewed as an access boundary
open	OIDC only	Any identity successfully authenticated by that exact issuer becomes a Member	Only when the OIDC issuer itself is the intended membership boundary

required_group is checked on every sign-in. Removing a person from that provider group blocks new sessions, but does not delete their local record, documents, or audit history. The comparison is an exact string comparison: jiandu-members, /jiandu-members, and a directory DN are different values.

open does not mean anonymous. It trusts the configured issuer's authentication decision for membership, but it is broader than an invitation or group gate and should be chosen deliberately.

Protect authentication secret files

OIDC client secrets, LDAP search-bind passwords, and trusted-proxy shared secrets are referenced by path; Jiandu does not accept them inline. On Unix each file must be:

• a nonempty regular file of at most 4 KiB;
• owned for the Jiandu service and exactly mode 0600;
• a single link, not a hard link or symlink; and
• UTF-8 text with no control characters (one final newline is removed).

Create a secret without exposing it through a process argument:

umask 077
install -d -m 0700 /etc/jiandu/secrets
read -r -s provider_secret
printf '%s\n' "$provider_secret" > /etc/jiandu/secrets/provider-secret
unset provider_secret
chmod 0600 /etc/jiandu/secrets/provider-secret

In containers, mount the file read-only at the configured path. A container-secret abstraction is suitable only if the resulting in-container file satisfies those ownership, mode, link, and size checks. Keep these deploy-time secrets outside the sole Jiandu recovery backup; restore needs the same provider configuration and secrets supplied separately.

Roll out one boundary at a time

1. Preserve and test the Owner recovery token through a protected channel.
2. Create one named human Administrator and verify its local sign-in.
3. Configure reverse proxy and HTTPS before any remote passkey, OIDC, or trusted-proxy setup.
4. Add one provider with invitation_only first, then restart Jiandu.
5. Confirm the enabled method registry and complete a real clean-browser sign-in.
6. Test both an allowed identity and an identity that must be denied.
7. Only then change to required_group or OIDC open, if that broader admission is intended.

All provider registry entries are file-only, have stable lowercase URL-safe IDs, and require a restart. Up to 16 providers may be configured. Renaming an ID creates a new provider namespace and changes OIDC callback routes, so treat IDs as permanent.

Validate syntax before the restart:

jiandu --config /etc/jiandu/jiandu.json --check-config
curl --fail --silent https://documents.example.net/api/v1/auth/methods | jq

The methods response intentionally exposes only method availability, provider IDs, and display names—not issuers, secrets, admission rules, or account details. Continue with the guide for the method you selected.