#### 3.2.15 The `auth` Statement ¶

#### Syntax ¶

    auth {
      # Set a list of modules for authentication.
      authentication module-list;

      # Set a list of modules for authorization.
      authorization module-list;
    }

#### Description ¶

Some mail utilities provide access to their services only after verifying that the user is actually the person he is claiming to be. Such programs are, for example, `pop3d` and `imap4d`. The process of the verification is broken down into two stages: authorization and authentication. In authorization stage the program retrieves the information about a particular user. In authentication stage, this information is compared against the user-supplied credentials. Only if both stages succeed is the user allowed to use the service.

A set of modules is involved in performing each stage. For example, the authorization stage can retrieve the user description from various sources: system database, SQL database, virtual domain table, etc. Each module is responsible for retrieving the description from a particular source of information. The modules are arranged in a module list. The modules from the list are invoked in turn, until one of them succeeds or the list is exhausted. In the latter case the authorization fails. Otherwise, the data returned by the succeeded module are used in authentication.

Similarly, authentication may be performed in several ways. The authentication modules are also grouped in a list. Each module is tried in turn until either a module succeeds, in which case the authentication succeeds, or the end of the list is reached.

For example, the authorization list

      (system, sql, virtdomains)

means that first the system user database (`/etc/password`) is searched for a description of a user in question. If the search fails, the SQL database is searched. Finally, if it also fails, the search is performed in the virtual domain database.

Note, that some authentication and/or authorization modules may be disabled when configuring the package before compilation. The names of the disabled modules are nevertheless available for use in runtime configuration options, but they represent a “fail-only” functionality, e.g. if the package was compiled without SQL support then the module ‘`sql`’ in the above example will always fail, thus passing the execution on to the next module.

The `auth` statement configures authentication and authorization.

Configuration: authorization module-list ¶

  Define a sequence of modules to use for authorization. Modules will be tried in the same order as listed in module-list.

  The modules available for use in authorization list are:

  system

    User credentials are retrieved from the system user database (`/etc/password`).

  sql

    User credentials are retrieved from a SQL database. A separate configuration statement, `sql`, is used to configure it (see The `sql` Statement).

  virtdomain

    User credentials are retrieved from a “virtual domain” user database. Virtual domains are configured using `virtdomain` statement (see The `virtdomain` Statement).

  radius

    User credentials are retrieved using RADIUS. See The `radius` Statement, for a detailed description on how to configure it.

  ldap

    User credentials are retrieved from an LDAP database. See The `ldap` Statement, for an information on how to configure it.

  Unless overridden by `authorization` statement, the default list of authorization modules is:

  1. generic
  2. system
  3. pam
  4. sql
  5. virtual
  6. radius
  7. ldap

Configuration: authentication module-list ¶

  Define a sequence of modules to use for authentication. Modules will be tried in the same order as listed in module-list.

  The following table lists modules available for use in module-list:

  generic

    The generic authentication type. User password is hashed and compared against the hash value returned in authorization stage.

  system

    The hashed value of the user password is retrieved from `/etc/shadow` file on systems that support it.

  sql

    The hashed value of the user password is retrieved from a SQL database using query supplied by `getpass` statement (see getpass).

  pam

    The user is authenticated via pluggable authentication module (PAM). The PAM service name to be used is configured in `pam` statement (see PAM Statement).

  radius

    The user is authenticated on a remote RADIUS server. See The `radius` Statement.

  ldap

    The user is authenticated using LDAP. See The `ldap` Statement.

  Unless overridden by `authentication` statement, the list of authentication modules is the same as for `authorization`, i.e.:

  1. generic
  2. system
  3. pam
  4. sql
  5. virtual
  6. radius
  7. ldap