Local User Configuration#

Local users are the built-in credential store in Tinyauth, distinct from LDAP and OAuth providers. They are defined in AuthConfig.Users as a list of username:hashed_password entries, or loaded from an external file via AuthConfig.UsersFile. Per-user OIDC attributes (name, email, locale, address, etc.) are attached via a separate AuthConfig.UserAttributes map keyed by username.

User Entry Format#

Each entry follows the format username:bcrypt_hash or username:bcrypt_hash:totp_secret. Parsing happens in ParseUser(), which splits on : (up to 3 parts) and populates the LocalUser struct:

Docker Compose note: bcrypt hashes contain $ characters. When passing via environment variables in Docker Compose, escape each $ as $$ — e.g., TINYAUTH_AUTH_USERS=user:$$2a$$10$$....

Passwords are verified with bcrypt via CheckUserPassword(). During login, SearchUser() checks local users first before falling back to LDAP.

User Attributes (OIDC Profile Claims)#

Auth.UserAttributes is a map[string]UserAttributes where each key is a username. The UserAttributes struct covers all standard OIDC profile claims:

Defaults when attributes are unset: If Name is empty, the context middleware capitalizes the username 1. If Email is empty, it constructs username@<cookie-domain> — or returns the username as-is if it already parses as a valid email address 2 3.

Configuration reference:

• Env var: TINYAUTH_AUTH_USERATTRIBUTES_[NAME]_EMAIL, TINYAUTH_AUTH_USERATTRIBUTES_[NAME]_NAME, etc. 4
• YAML: auth.userAttributes.<username>.email, auth.userAttributes.<username>.name, etc.

OIDC Claim Mapping#

When Tinyauth acts as an OIDC provider and a local user authenticates, userinfoFromContext() populates all UserAttributes fields into the userinfo response. Unlike LDAP/OAuth users (which only get groups passed through), local users get the full profile claim set 5.

The OIDC sub claim is a deterministic UUID derived from username:clientId, making it stable across sessions but tied to the username 6.

TOTP and Basic Auth Restriction#

A TOTP secret is stored as the third colon-separated field in the user entry. Users with a non-empty TOTPSecret cannot authenticate via Basic Auth — the basicAuth() handler rejects them 7 because there is no second-factor channel in that flow.

Key Source Files#