Key-value authentication database (v2.1.9+)
===========================================

Key-value databases can be used as auth backends. They probably should be used
only for caching in front of e.g. SQL auth backends. Iteration is supported if
the underlying dict provider supports iteration. See <Dictionary.txt> for list
of supported databases.

Auth configuration
------------------

'dovecot.conf':

---%<-------------------------------------------------------------------------
passdb {
  driver = dict
  args = /etc/dovecot/dovecot-dict-auth.conf
}
userdb {
  driver = dict
  args = /etc/dovecot/dovecot-dict-auth.conf
}
---%<-------------------------------------------------------------------------

Dict configuration
------------------

You can use userdb: prefix for accessing userdb variables (v2.2.26+).

---%<-------------------------------------------------------------------------
uri = redis:host=127.0.0.1:port=6379

password_key = dovecot/passdb/%u
user_key = dovecot/userdb/%u
iterate_disable = yes
default_pass_scheme = plain

## or the new syntax

key passdb {
  key = dovecot/passdb/%u
  passdb_objects = passdb
}

key userdb {
  key = dovecot/userdb/%u
  userdb_objects = userdb
}
---%<-------------------------------------------------------------------------

Example values
--------------

Currently only JSON object values are supported. For example userdb lookup
should return something like:

---%<-------------------------------------------------------------------------
{ "uid": 123, "gid": 123, "home": "/home/username" }
---%<-------------------------------------------------------------------------

== Complete example for authenticating via the CDB dictionary This example uses
the CDB dictionary to store the userdb and passdb.

Auth configuration
------------------

'dovecot.conf':

---%<-------------------------------------------------------------------------
# Access to the CDB has to go through a dict process.
dict {
  auth = cdb:/etc/dovecot/auth.cdb
}

passdb {
  driver = dict
  args = /etc/dovecot/dovecot-cdb.conf
}

userdb {
  driver = dict
  args = /etc/dovecot/dovecot-cdb.conf
}
---%<-------------------------------------------------------------------------

Dict configuration
------------------

The CDB dictionary doesn't support iteration yet.

'dovecot-cdb.conf':

---%<-------------------------------------------------------------------------
uri = proxy::auth

password_key = passdb/%u
user_key = userdb/%u
# iterate_prefix = userdb/ # no yet supported
iterate_disable = yes

default_pass_scheme = BLF-CRYPT
---%<-------------------------------------------------------------------------

Complete example for authenticating via a UNIX socket
-----------------------------------------------------

The Dict auth backend can be used to query a local UNIX socket for users. This
can be handy for accessing user databases which would otherwise only be
accessible via the <CheckPassword> [AuthDatabase.CheckPassword.txt] backend and
a scripting language.

When given a <"proxy:"> [Quota.Dict.txt] URL the Dict backend speaks a simple
protocol over a UNIX socket. The protocol is defined in
'src/lib-dict/dict-client.h' (GitHub
[https://github.com/dovecot/core/blob/master/src/lib-dict/dict-client.h]).

Auth configuration
------------------

'dovecot.conf':

---%<-------------------------------------------------------------------------
passdb {
  driver = dict
  args = /etc/dovecot/dovecot-dict-auth.conf
}
userdb {
  # optional
  driver = prefetch
}
userdb {
  driver = dict
  args = /etc/dovecot/dovecot-dict-auth.conf
}
---%<-------------------------------------------------------------------------

Dict configuration
------------------

The last "dictionary name" ("somewhere") argument is redundant here.

'/etc/dovecot/dovecot-dict-auth.conf.ext':

---%<-------------------------------------------------------------------------
uri = proxy:/var/run/auth_proxy_dovecot/socket:somewhere

password_key = passdb/%u
user_key = userdb/%u
iterate_disable = yes
#default_pass_scheme = plain
---%<-------------------------------------------------------------------------

Server process for answering Dict lookups
-----------------------------------------

The server process listening on '/var/run/auth_proxy_dovecot/socket' can be
written in any language.Here's an example in Perl:

---%<-------------------------------------------------------------------------
package AuthProxyDovecot;
use base qw( Net::Server::PreFork );

use strict;
use warnings;

use JSON::XS;

AuthProxyDovecot->run() or die "Could not initialize";

sub default_values
{
  return {
    port              => '/var/run/auth_proxy_dovecot/socket|unix',

    log_level         => 2,
    log_file          => 'Sys::Syslog',
    syslog_logsock    => 'unix',
    syslog_ident      => 'auth_proxy_dovecot',
    syslog_facility   => 'daemon',

    background        => 1,
    setsid            => 1,
    pid_file          => '/var/run/auth_proxy_dovecot.pid',

    user              => 'root',
    group             => 'root',

    max_spare_servers => 2,
    min_spare_servers => 1,
    min_servers       => 2,
    max_servers       => 10,

  };
} ## end sub default_values

##################################################

sub process_request {
    my $self   = shift;

    my %L_handler = (
        passdb => sub {
            my ($arg) = @_;
            my $ret = {
                password        => '$1$JrTuEHAY$gZA1y4ElkLHtnsrWNHT/e.',
                userdb_home     => "/home/username/",
                userdb_uid      => 1000,
                userdb_gid      => 1000,
            };
            return $ret;
        },
        userdb => sub {
            my ($arg) = @_;
            my $ret = {
                home    => "/home/username/",
                uid     => 1000,
                gid     => 1000,
            };
            return $ret;
        },
    );

    # protocol from src/lib-dict/dict-client.h
    my $json = JSON::XS->new;

    eval {
        my $ret;
        # Dict protocol is multiline... go through the lines.
        while (<STDIN>) {
            $self->log(2, "Got request: $_");
            chomp;
            my $cmd = substr($_,0,1);
            next if $cmd eq 'H'; # "hello", skip this line, assume it's ok
            die "Protocol error: Bad command $cmd" unless ($cmd eq 'L');
            # Process request

                my ($namespace,$type,$arg) = split ('/',substr($_,1),3);

                if ($namespace eq 'shared') {
                    my $f = $L_handler{$type};

                    if (defined $f && defined $arg) {
                    $ret = $f->($arg);
                    }
                else {
                    die 'Protocol error: Bad arg';
                }
                }
            else {
                die 'Protocol error: Bad namespace'
            }
            last; # Got an "L" , now respond.
        }
        if ($ret) {
            my $json = JSON::XS->new->indent(0)->utf8->encode($ret);
            $self->log(3,"O:$json");
            print "O".$json."\n";
        }
        else {
            $self->log(3,"NOUSER");
            print "N\n";
        }
        1;
    } or do {
        $self->log(2, "Error: $@");
        print "F\n";
    };
}

sub pre_loop_hook {
    my $self = shift;

    $self->log(1, 'Starting server');
}

sub pre_server_close_hook {
    my $self = shift;

    $self->log(1, 'Server is shut down');
}

1;

__END__
---%<-------------------------------------------------------------------------

(This file was created from the wiki on 2017-10-10 04:42)