Usage

Example:

   $connector->get('username', {  password => 'mySecret' } );

To configure module for direct bind, the connector object should be created with parameter indirect => 0. This is the simplest authentication method and requires least parameters to be configured.

Example:

    my $connector = Connector::Builtin::Authentication::LDAP->new({
        LOCATION => 'ldap://ldap.example.org',
        indirect => 0
    })
    my $result = $connector->get(
        'uid=jsmith,ou=people,dc=example,dc=org',
        { password => 'secret' }
    );

Indirect bind, which is default, searches through the LDAP directory. This usually requires read access to database, and is performed by a separate user. We'll call that user binddn. For indirect-bind authentication, one usually has to provide DN and password of the existing binddn user.

Example:

    my $connector = Connector::Builtin::Authentication::LDAP->new({
        LOCATION => 'ldap://ldap.example.org',
        binddn => 'cn=admin,dc=example,dc=org',
        password => 'binddnPassword'
    })
    my $result = $connector->get('jsmith', { password => 'secret' });

Two parameters are used to check group participation: groupdn and groupattr. The groupdn parameter specifies DN of a group entry and the groupattr specifies an attribute of the groupdn object where group participants are listed. If you specify groupdn, the group participation check is enabled.

Example:

    # Assume, we have in LDAP:
    #
    # dn: cn=vip,dc=example,dc=org
    # objectClass: groupOfNames
    # member: uid=jsmith,ou=people,dc=example,dc=org
    #
    my $connector = Connector::Builtin::Authentication::LDAP->new({
        LOCATION => 'ldap://ldap.example.org',
        indirect => 0,
        binddn => 'cn=admin,dc=example,dc=org',
        password => 'binddnPassword',
        groupdn => 'cn=vip,dc=example,dc=org',
    })
    my $result = $connector->get(
        'uid=jsmith,ou=people,dc=example,dc=org',
        { password => 'secret' }
    );

Note, that in this case we have provided binddn despite the direct-bind authentication was used. This is, because we needed read access to the "cn=vip,dc=example,dc=org" entry (the group object).

The indirect-bind method accepts custom filters for user search.

Example:

    my $connector = Connector::Builtin::Authentication::LDAP->new({
        LOCATION => 'ldap://ldap.example.org',
        binddn => 'cn=admin,dc=example,dc=org',
        password => 'binddnPassword',
        filter => '(&(uid=[% LOGIN %])(accountStatus=active))'
    })
    my $result = $connector->get('jsmith', { password => 'secret' });

You may substitute user name by using [% LOGIN %] template parameter, as shown in the above example.

Configuration

Connection options

See Connector::Proxy::Net::LDAP

SSL Connection options

verify => 'none' | 'optional' | 'require'

How to verify the server's certificate:

    none
        The server may provide a certificate but it will not be checked - this
        may mean you are be connected to the wrong server
    optional
        Verify only when the server offers a certificate
    require
        The server must provide a certificate, and it must be valid.
    

If you set verify to optional or require, you must also set either cafile or capath. The most secure option is require.

sslversion => 'sslv2' | 'sslv3' | 'sslv23' | 'tlsv1'

This defines the version of the SSL/TLS protocol to use. Defaults to 'tlsv1'.

ciphers => CIPHERS

Specify which subset of cipher suites are permissible for this connection, using the standard OpenSSL string format. The default behavior is to keep the decision on the underlying cryptographic library.

capath => '/path/to/servercerts/'

See cafile.

cafile => '/path/to/servercert.pem'

When verifying the server's certificate, either set capath to the pathname of the directory containing CA certificates, or set cafile to the filename containing the certificate of the CA who signed the server's certificate. These certificates must all be in PEM format.

clientcert => '/path/to/cert.pem'

See clientkey.

clientkey => '/path/to/key.pem'

If you want to use the client to offer a certificate to the server for SSL authentication (which is not the same as for the LDAP Bind operation) then set clientcert to the user's certificate file, and clientkey to the user's private key file. These files must be in PEM format.

checkcrl => 1

BindDN

binddn => DN

Distinguished Name of the LDAP entry used to search LDAP database for users being authenticated (indirect bind) and check their group participation.

password => PASSWORD

Password for the binddn user.

Search options (indirect bind)

timelimit => N

A timelimit that restricts the maximum time (in seconds) allowed for a search. A value of 0 (the default), means that no timelimit will be requested.

sizelimit => N

A sizelimit that restricts the maximum number of entries to be returned as a result of the search. A value of 0, and the default, means that no restriction is requested. Servers may enforce a maximum number of entries to return.

base => DN

The DN that is the base object entry relative to which the search is to be performed.

filter => TEMPLATESTRING

A filter that defines the conditions an entry in the directory must meet in order for it to be returned by the search. This may be a (template) string or a Net::LDAP::Filter object.

scope => 'base' | 'one' | 'sub' | 'subtree' | 'children'

By default the search is performed on the whole tree below the specified base object. This maybe changed by specifying a scope parameter with one of the following values:

    base
        Search only the base object.
    one
        Search the entries immediately below the base object.
    sub
    subtree
        Search the whole tree below (and including) the base object. This is
        the default.
    children
        Search the whole subtree below the base object, excluding the base object itself.
    

Note: children scope requires LDAPv3 subordinate feature extension.

Other options

userattr => ATTRNAME

If the search filter (for indirect bind) is not specified, it is constructed internally as "($userattr=[% LOGIN %])", where $userattr represents the value of userattr parameter.

groupattr => ATTRNAME

If groupdn is specified by caller, the groupattr defines an attribute within groupdn object which shall be compared against the DN of the user being authenticated in order to check its participation to the group. Defaults to 'member'.

groupdn => DN

DN of an LDAP entry which defines a group of users allowed to be authenticated. If not defined, the group participation is not checked.

indirect => 1 | 0

Use indirect bind (default). Set to 0 to disable indirect bind and use direct bind.

ambiguous => 0 | 1

Accept ambiguous search results when doing indirect-bind authentication. By default, this option is disabled.

Return values

Limitations