Login and Sessions

This page explains two layers

• [auth] in config.toml - only handles static startup bootstrap: signing secrets and the first plain-HTTP bootstrap
• Admin -> System Settings - daily rules: public registration, cookies, token TTLs, activation/reset links, and cooldowns

In normal operation, almost everything you actually change is in the admin console. The static part on this page is usually touched only once during initial deployment or migration to another machine.

[auth] in config.toml

[auth]
jwt_secret = "<random secret generated on first startup>"
mfa_secret_key = "<random secret generated on first startup>"
bootstrap_insecure_cookies = false

jwt_secret

When the configuration is generated for the first time, the service writes a random secret. You can think of it as the "site-wide login signing secret".

Keep it stable in production

Once changed:

• All current login sessions become invalid
• Password verification cookies for public shares become invalid
• Everyone must log in again

mfa_secret_key

This is the server-side encryption key for MFA/TOTP secrets. When the configuration is generated for the first time, the service automatically writes a random value.

Preserve it during backup and migration

If users have already enabled MFA, do not casually replace it while migrating, restoring, or rebuilding config.toml.

Once changed, existing authenticator secrets can no longer be decrypted, and users with MFA enabled cannot complete two-step verification with their old authenticator. An administrator can only reset that user's MFA from Admin -> Users -> User Details -> Security Actions, then ask the user to bind an authenticator again and save new recovery codes.

bootstrap_insecure_cookies

• First plain-HTTP trial run - temporarily set it to true
• Production HTTPS deployment - keep it false

It only affects the default value written when auth_cookie_secure is initialized for the first time. If this runtime system setting already exists in the database, changing this value will not rewrite the old value.

The Login Page Chooses the Flow by State

The login page is not a fixed "login" or "register" page. It follows the current state:

• There are no users in the system yet - enter initialization and create the first administrator directly
• Users already exist, and the entered account exists - log in
• Users already exist, the entered account is new, and the administrator allows public registration - create a normal account
• The administrator enabled an external authentication provider - the login page shows the corresponding external login entry
• The current browser supports Passkey - the login page shows the Passkey login entry, and accounts with registered Passkeys can log in directly with device unlock or a security key
• The account enabled MFA - after password or external identity succeeds, the user must also enter an authenticator code or recovery code

Important details:

• The first account becomes an administrator directly and does not go through email activation
• Later normal accounts created through public registration must click the activation email before logging in
• After the administrator disables public registration, the login page only keeps login and password recovery

MFA Multi-Factor Authentication

Users enable MFA themselves here:

Settings -> Security -> Multi-Factor Authentication

AsterDrive currently supports TOTP authenticator apps. Common apps include 1Password, Bitwarden, Google Authenticator, and Microsoft Authenticator.

The enablement flow is roughly:

1. Open Settings -> Security -> Multi-Factor Authentication
2. Click set up authenticator
3. Scan the QR code with an authenticator app, or enter the secret manually
4. Enter the 6-digit code generated by the authenticator to finish binding
5. Download or copy recovery codes, and save them in a password manager or another secure location

Recovery codes are shown in plaintext only once when generated, and each recovery code can be used only once. If the authenticator is lost, a recovery code can complete MFA verification on the login page. After logging in, regenerate recovery codes or bind an authenticator again as soon as possible.

After MFA is enabled, these login methods enter second-step verification:

• Local password login
• External authentication login

Passkey login does not enter the MFA challenge described here. It relies on device unlock or a security key for user verification, and is a separate login path from "password/external identity + TOTP".

The MFA login verification flow is valid for 5 minutes by default and allows at most 5 attempts. If verification expires or attempts are exhausted, return to the login page and start again.

If a user loses both the authenticator and recovery codes, an administrator can reset it here:

Admin -> Users -> User Details -> Security Actions -> Reset MFA

Resetting clears that user's authenticator, recovery codes, and unfinished MFA login flows, and invalidates the user's existing sessions. The user must set up MFA again after the next login.

Passkey Login

Passkey is a login method managed by each user. The entry point is:

Settings -> Security -> Passkey

Users can:

• Add new Passkeys
• Rename a Passkey, such as MacBook, iPhone, or a specific security key
• View creation time and last-used time
• Delete Passkeys that are no longer used

When adding a Passkey, the browser opens the system WebAuthn / Passkey verification window. For production deployments, first configure Admin -> System Settings -> Site Configuration -> Public Site URL correctly and use HTTPS. Local localhost / 127.0.0.1 debugging is the exception. Browsers usually expose the full Passkey capability only in secure contexts.

Passkeys do not replace local passwords. Users can continue logging in with passwords. After deleting a Passkey, only that device or security key can no longer log in to the current account directly.

External Authentication / SSO

Administrators can connect external identity providers here:

Admin -> External Authentication

AsterDrive currently includes OpenID Connect support. After creating a provider, the login page shows the corresponding external login entry. The administrator must register the generated redirect URI on the identity provider side.

The relationship between external identities and local users is determined by provider rules:

• Previously bound external identities log in to the corresponding local user directly
• After "auto-bind by verified email" is enabled, if the identity provider returns email_verified=true and exactly one local user has the same email address, the system can bind automatically
• After "auto-create local users" is enabled, unbound identities can automatically create normal users
• Without auto-bind or auto-create, the user must first log in to an existing account to complete binding, or continue through the email verification flow

Users can view and unlink external identities they have already bound here:

Settings -> Security -> External Identities

If the administrator enabled auto-bind, an external login that matches the same rules may still bind back to the local account after the user unlinks it.

Where Is the Public Registration Switch?

Admin -> System Settings -> User Management -> Allow Public User Registration

After it is disabled:

• External users can no longer create new accounts from the login page
• The first-administrator initialization flow still exists
• Users manually created by administrators in the admin console still work

Which Features Depend on Mail Configuration?

These features do not work without mail:

• Activation email after public registration
• Password recovery on the login page
• Email address change confirmation email in Settings -> Security
• Email verification flow when external authentication cannot directly match a local account

Configure mail before enabling registration

If you do it in the wrong order, new user accounts may already be created but cannot receive activation emails, so they remain stuck at "waiting for activation".

Before enabling these capabilities, check together:

1. Admin -> System Settings -> Mail Delivery
2. Admin -> System Settings -> Site Configuration -> Public Site URL
3. If you are connecting external authentication, also check whether the redirect URI in Admin -> External Authentication has been registered on the identity provider side

Common Examples

Local or Intranet HTTP Trial Run

[auth]
bootstrap_insecure_cookies = true

Production HTTPS Deployment

[auth]
jwt_secret = "replace-with-your-own-secret"
mfa_secret_key = "replace-with-another-stable-secret"
bootstrap_insecure_cookies = false

Environment variable overrides:

ASTER__AUTH__JWT_SECRET="replace-with-your-own-secret"
ASTER__AUTH__MFA_SECRET_KEY="replace-with-another-stable-secret"
ASTER__AUTH__BOOTSTRAP_INSECURE_COOKIES=false

The Settings You Actually Change Day to Day Are in the Admin Console

The following settings are not in config.toml; they are all maintained in the admin console:

• auth_cookie_secure - Whether cookies are sent only over HTTPS
• auth_access_token_ttl_secs - Access token TTL
• auth_refresh_token_ttl_secs - Refresh token TTL
• auth_register_activation_ttl_secs - Registration activation link TTL
• auth_contact_change_ttl_secs - Email address change link TTL
• auth_password_reset_ttl_secs - Password reset link TTL
• auth_contact_verification_resend_cooldown_secs - Verification email resend cooldown
• auth_password_reset_request_cooldown_secs - Password reset request cooldown
• auth_allow_user_registration - Public registration switch
• auth_register_activation_enabled - Whether newly registered users must complete email activation first
• External authentication email verification mail template - In the Mail Delivery group, used when an external identity cannot directly match a local account

See runtime system settings for details.