Master users

A master user is an administrative identity allowed to log into another user's mailbox with its own password — the target's password is never involved. Typical uses: mailbox migrations, support access, automated per-user maintenance.

The feature is off by default. With it off, any login that names a second identity is refused before the password database is consulted.

Configuration

Enable the feature and give it a master password database:

auth:
  master_users:
    enabled: true
    auth_master_user_separator: "*"
    masterdb:
      - driver: mysql
        dsn: "${YARILO_DB_DSN}"
        skip_schema: true
        passdb_sql_query: |
          SELECT password, active AS enabled
          FROM masters
          WHERE username = %u

Setting	Default	Notes
enabled	false	Master switch. Off refuses every impersonation attempt before the chain runs.
masterdb	—	A dedicated passdb chain for master credentials. Same drivers and fields as auth.passdb (sql, passwd-file, …).
auth_master_user_separator	*	Separator for the legacy login form below. Empty disables that form; the SASL form keeps working.

Grants come from either of two places: a hit in masterdb, or a true master_user field (master_user=yes) on an ordinary passdb answer — a column alias in passdb_sql_query, a bare key in a passwd-file line. A user found in neither is refused as a master regardless of its password.

Helm

components:
  auth:
    master_users:
      enabled: true
      separator: "*"
      masterdb:
        - driver: mysql
          dsn: "${YARILO_DB_DSN}"
          skip_schema: true
          password_query: |
            SELECT password, active AS enabled FROM masters WHERE username = %u

separator is auth_master_user_separator, and a masterdb entry uses the chart's passdb names (password_query, passwd_file, …) as described in Authentication → Helm. From 2.4.2 an empty separator reaches the config and turns the separator form off, and auth_master_user_separator under master_users fails the render and names separator. In 2.4.1 an empty separator is rendered as *, so the separator form cannot be turned off through the chart (yarilo#2162).

Logging in as another user

Two forms are accepted.

SASL authzid (preferred). RFC 4616 PLAIN carries three fields; the first names the target, the second the master:

AUTHENTICATE PLAIN base64(target \0 master \0 master-password)

Separator form — for clients that cannot send an authzid (older Outlook, some mobile MUAs, and POP3's USER/PASS, which has no authzid at all):

LOGIN target*master master-password
USER target*master        (POP3)

Both resolve to the same thing: the session authenticates with the master's credentials and then acts entirely as the target — the director routes by the target, connection accounting counts the target, and an administrative kick for the target finds the session.

Prefer the authzid form

The separator form exists as a compatibility workaround: a username that legitimately contains the separator character becomes ambiguous, and the raw login string is visible wherever the client string is logged. Use SASL authzid whenever the client can send it.

Isolation

A master session sees exactly the target's mailbox — the master has no mailbox of its own. Writes land in the target's state: a flag set by the master is visible to the target's own next login.

Audit

Every master login is written with both identities, so an impersonation is never invisible in the log:

auth: ok  [email protected]  master_user=admin-master  result=ok

The client-typed string (for the separator form, target*master) appears only in the lines that quote what the client sent.