Authentication (GNU Dico Manual)

4.3.3 Authentication

The server may be configured to request authentication in order to make some databases or some additional information available to the user. Another possible use of authentication is to minimize resource utilization on the server machine.

GNU Dico supports two types of authentication: the traditional APOP-style authentication (see The AUTH Command) and a more advanced SASL authentication. The latter is described separately, see SASL Authentication.

Authentication setup is simple: first, you define a user authentication database, then you enable it by declaring auth server capability (see Server Capabilities):

capability auth;

User authentication database keeps, for each user name, the corresponding plain text password, and, optionally, the names of groups this user belongs to. Notice, that due to the specifics of DICT authentication scheme (see The AUTH Command), user passwords are stored in plain text, therefore special care must be taken to protect the contents of your authentication database from compromise.

The database is defined using the user-db block statement:

Configuration: user-db url ¶: Declare user authentication database.

Dico’s authentication is designed so that various authentication database formats can easily be added. A database is identified by its URL, or Universal Resource Locator. It consists of the following parts (square brackets denoting optional ones):

type://[[user[:password]@]host]/path[params]

type: A database type, or format. See below for a list of available database formats.
user: User name necessary to access the database.
password: User password necessary to access the database.
host: Domain name or IP address of a machine running the database.
path: A path to the database. The exact meaning of this element depends on the database protocol. It is described in detail when discussing the particular database protocols.
params: A list of protocol-dependent parameters. Each parameter is of the form keyword=name, multiple parameters are separated with semicolons.

If the underlying mechanism requires some additional configuration data that cannot be supplied in an URL, these are passed to it using the following statement:

user-db conf: options string ¶: The argument is treated as an opaque string and passed to the authentication ‘open’ procedure verbatim. Its exact meaning depends on the type of the database.

The URL defines how the database is accessed. Another important point is where to get the user data from. This is specified by the following two sub-statements:

user-db conf: password-resource arg ¶: A database resource which returns the user’s password.

user-db conf: group-resource arg ¶: A database resource which returns the list of groups this user is member of.

The exact semantics of the database resource depends on the type of database being used. For flat text databases, it means the name of a text file that contains these data, for SQL databases, the resource is an SQL query, etc. Below we will discuss URLs and resources used by each database type.

To summarize, the authentication database is defined as:

# Define user database for authentication.
user-db url {
  # Additional configuration options.
  options string;
  
  # Name of a password resource.
  password-resource resource;

  # Name of the resource returning user group information.
  group-resource resource;
}