NAME
    Apache2::AuthenCacheLDAP - mod_perl2 LDAP Authentication Module

SYNOPSIS
    Here is a simple authentication configuration. No single signon and user
    simple authentication:

        <Directory "/opt/foo">
            AllowOverride All
            Options ExecCGI FollowSymLinks
            # Authentication Realm and Type (only Basic supported)
            AuthName "Foo Authentication"
            AuthType Basic
            PerlSetVar BaseDN "ou=people,dc=foo,dc=com"
            PerlSetVar LDAPServer "ldap.foo.com"
            PerlSetVar LDAPPort "389"
            PerlSetVar UIDAttr "uid"
            PerlAuthenHandler Apache2::AuthenCacheLDAP
            require valid-user
            Order allow,deny
            Allow from all
        </Directory>

    Here the more complexe authentication setting you can do with this
    module with single signon (cookie caching) and user/group
    authentication:

        <Directory "/opt/foo">
            AllowOverride All
            Options ExecCGI FollowSymLinks
            # Authentication Realm and Type (only Basic supported)
            AuthName "Foo Authentication"
            AuthType Basic
            AuthGroupFile /dev/null
            PerlSetVar AuthCache "on"
            PerlSetVar AuthCacheSuppressPort "on"
            PerlSetVar BaseDN "ou=people,dc=foo,dc=com"
            PerlSetVar LDAPServer "ldap.foo.com"
            PerlSetVar LDAPPort "389"
            PerlSetVar UIDAttr "uid"
            PerlSetVar UserGroupDN "ou=group,dc=foo,dc=com" 
            PerlSetVar GRPAttr "memberUid"
            PerlSetVar LinkAttr "employeeNumber"
            PerlSetVar ExtraAttr "cn;departmentNumber;mail"
            PerlSetVar AllowGroup "intranet"
            PerlAuthenHandler Apache2::AuthenCacheLDAP
            require ldap-group support_info
            require valid-user
            satisfy all
            Order allow,deny
            Allow from all
        </Directory>

    It also set and restore three LDAP based variable: cn, departmentNumber,
    mail that you can acces with $ENV{REMOTE_CN},
    $ENV{REMOTE_DEPARTMENTNUMBER} and $ENV{REMOTE_MAIL}

DESCRIPTION
    Apache2::AuthenCacheLDAP is designed to work with mod_perl2 and
    Net::LDAP. This module authenticates a user against an LDAP backend.

    The authentication process is as follow:

    1) Connect to the LDAP server.

    2) Check if the given user is allowed if require user is set.

    3) Authenticate with the given login/password.

    4) Authenticate with group if BaseGroupDN and AllowGroup is set.

    Additionnaly this module allow single signon based on a domain and
    caching by using cookie. It also allow setting of Apache environment
    variable based on the LDAP attribute.

AUTHENTICATION CONFIGURATION OPTIONS
    The following variables can be defined within the configuration of
    Directory, Location, or Files blocks or within .htaccess files.

    BaseDN
        The base distinguished name with which to query LDAP. By default,
        the BaseDN is empty.

    LDAPServer
        The hostname for the LDAP server to query. By default, LDAPServer is
        set to localhost. To allow failover, you can pass a list of LDAP
        server separated by semi colon

        example : master.domain.com;slave1.domain.com;slave2.domain.com

        When the perl module try to connect to a server and the connection
        fail, it goes to the second server, etc.

    LDAPPort
        The port on which the LDAP server is listening. By default,
        AuthenCacheLDAPPort is set to 389.

    UidAttr
        The attribute name that contains the user's identification. By
        default, UidAttr is set to uid.

    BaseGroupDN
        The base distinguished name used to query a LDAP posix group. By
        default, the BaseGroupDN is empty.

    GRPAttr
        The attribute name that contains the user's identification into the
        posix group object. By default, GRPAttr is set to memberUid. And the
        value is retrieved from the UidAttr value.

    LinkAttr
        The attribute name that contains the user's identification to search
        into the posix group object as value of the GRPAttr. See above. By
        default, LinkAttr is set to the UidAttr.

        This is to use if the user DN is not based on the standard uid
        attribute. For example if your dn is
        employeeNumber=xxxx,dc=domain,dc=com and the unique member on posix
        group is based on the employeeNumber. You may not be able to
        authenticate to group if authentication is based on uid attribute.
        So this will help to match any LDAP structure.

    UserGroupDN
        The base distinguished name with which to query all LDAP posix group
        LDAP that a user belongs to. By default, the UserGroupDN is empty.

        This will set the Apache environment variable REMOTE_GROUP with the
        require group and an other variable REMOTE_ALLGROUP with a string
        containing all groups of the user separated by a ';'

    ExtraAttr
        The attribute name that contains a list of LDAP attributes name
        separated with a ';' that you may want to be return as an Apache
        environment variable. The Apache environment variable will be named
        'REMOTE_' . uc(ExtraAttr). By default, ExtraAttr is empty.

        example: PerlSetVar ExtraAttr "departmentNumber;employeeNumber" will
        return two Apache environment variable:

        REMOTE_DEPARTMENTNUMBER and REMOTE_EMPLOYEENUMBER

        So you can use them into your perl CGI programs

    LogoutPattern
        The pattern to match in URI arguments to emulate a logout. By
        default, LogoutPattern is set to 'logout'. To disable this set it to
        "off".

        example: PerlSetVar LogoutPattern "?logmeoutofSSO" If this pattern
        is found into the arguments of the URL this module will expire the
        current session if the timestamp given as value of this argument is
        upper than the request time and then ask for authentication again.

        WARNING: the value of the argument must be a date in seconde like
        the value returned by the perl time function + some little delay.

        See LOGOUT.readme file for more information.

CACHING CONFIGURATION OPTIONS
    The following variables are used to enable the caching of authentication

    AuthCache
        Enable or disable auth caching. By default, AuthCache is set to off.
        To enable caching set it to on.

    AuthCacheSuppressPort
        Disable per port caching. By default, AuthCacheSuppressPort is set
        to off. To enable single signon on any apache listening port set it
        to on.

    AuthCacheSingleSignon
        Allow single signon on the current apache running domain. Default is
        off, no SSO. Set it to on to have SSO on all apache servers running
        on a single domain.

        Note that the AuthName must be the same on each servers. This module
        only support AuthType Basic.

        The name of the SSO cookie is build as follow:

                Apache-AuthCache-domain_name:server_port-auth_type:auth_name=VALUE

        where 'domain_name' is the second level domain name of the server,
        ex: .samse.fr, 'server_port' is the listening http port or 0 if
        AuthCacheSuppressPort is set to off. Here a complete example of a
        cookie name:

            Apache-AuthCache-.samse.fr:0-Basic:Intranet Authentication

        The VALUE of the cookie is build as follow:

                username:passwd:remote_ip:timestamp:remote_group:remote_allgroup:other_name=other_val

        the VALUE is base64 encoded, so it may only be used in a secure
        environment.

        'other_name' variables are those defined in the ExtraAttr perl
        directive and 'other_val' is the values of the corresponding LDAP
        attributes retrieved from LDAP directory.

        For example if you have defined a perl directive in the httpd.conf
        as follow:

            PerlSetVar ExtraAttr "departmentNumber;employeeNumber;codeAgence"

        the authentication module will retrieve the values of these LDAP
        attributes from the LDAP directory and 'other_name' and 'other_val'
        would be:

            departmentNumber=NNN:employeeNumber=NNN:codeAgence=NNN

        Here a complete example of the cookie value:

            gsample:Linux64:192.168.2.34:1076058109:intranet:;intranet;users;internet;:codeAgence=331:mail=guest-sample@samse.fr:cn=SAMPLE Guest:departmentNumber=344:employeeNumber=000111

        In this example the ExtraAttr perlvar directive is set as follow:

            PerlSetVar ExtraAttr "employeeNumber;departmentNumber;mail;codeAgence;cn"

        Note that in the remote_allgroup part of the cookie the separator of
        group name (;) could be present or not at begin and end of the
        section.

    AuthCacheTTL
        Time to live of caching in second. Default is 0, no expiration at
        all. Set it to the number second you want the cache expire.

AUTHORS
    Gilles Darold <gilles@darold.net>

See ALSO
    httpd(8), ldap(3), mod_perl(1), slapd(8C)

COPYRIGHT
    Copyright (C) 2002-2005, Gilles Darold - Groupe SAMSE All Rights
    Reserved.

    This module is free software; you can redistribute it and/or modify it
    under the terms of Perl itself.

