NAME

Apache2::AuthCookieLDAP - An Apache2::AuthCookie backend for LDAP based authentication

VERSION

Version 1.15

COMPATIBILITY

The version is compatible with Apache2 and mod_perl2

SYNOPSIS

1. Make sure that your LDAP server is configured and you have access to it

2. In httpd.conf or .htaccess

Apache2::AuthCookie config (check Apache2::AuthCookie documentation for the additional info)

    PerlSetVar MyAuthPath /
    PerlSetVar MyAuthLoginScript /
    PerlSetVar MyAuthLogoutURL http://127.0.0.1
    PerlSetVar MyAuthSecure 1

To make "LogoutURL" working you can subsclass Apache2::ApacheCookieLDAP and provide it with:

    sub logout {
        my ( $self, $r ) = @_;
        $self->SUPER::logout($r);
        my $logout_url = $r->dir_config( $r->auth_name . 'LogoutURL' );
        if ($logout_url) {
            $r->headers_out->set( Location => $logout_url );
            $r->status(Apache2::Const::REDIRECT);
        }

        return Apache2::Const::REDIRECT;
    }
  

Apache2::AuthCookieLDAP config

    PerlSetVar MyAuth_SecretKey OGheSWkT1ixd4V0DydSarLVevF77sSibMIoUaIYuQUqp2zvZIwbS4lyWhRTFUcHE
    PerlSetVar MyAuth_SessionLifetime 00-24-00-00
    PerlSetVar MyAuth_LDAPURI ldap://127.0.0.1
    PerlSetVar MyAuth_Base uid=%USER%,ou=staff,dc=company,dc=com
    PerlSetVar MyAuth_BindDN cn=ldap,dc=company,dc=com
    PerlSetVar MyAuth_BindPW somepassword
    PerlSetVar MyAuth_Filter (uid=%USER%)

    <Directory /var/www/mysite/protected>
        AuthType Apache2::AuthCookieLDAP
        AuthName MyAuth
        PerlAuthenHandler Apache2::AuthCookieLDAP->authenticate
        PerlAuthzHandler Apache2::AuthCookieLDAP->authorize
        require valid-user
    </Directory>

    <Location /login>
        SetHandler perl-script
        AuthType Apache2::AuthCookieLDAP
        AuthName MyAuth
        PerlResponseHandler MyAuthCookieLDAP->login
    </Location>

    <Location /logout>
        SetHandler perl-script
        AuthType Apache2::AuthCookieLDAP
        AuthName MyAuth
        PerlResponseHandler Apache2::AuthCookieLDAP->logout
    </Location>

DESCRIPTION

This module acts as an authentication handler under Apache2 environment. It uses Apache2::AuthCookie as the base class and serves as a backend to provide user authentication against an LDAP server.

Make sure that you have got a reachable LDAP server and credentials to access it (ldapuri, base, binddn/bindpw or anonymous bind).

When there is an attempt to access a "protected" directory or location that has 'require valid-user' option included Apache2::AuthCookieLDAP is used as the authentication and the authorization handler. It takes a pair of provided username/password and tries to search the username in the LDAP directory (it also uses the filter MyAuth_Filter, for puropses where you want to restrict access to the resource to only a specific group). If the user is found then it tries to bind with the provided username/password. Once authorized a session key is generated by taking into account the provided username, authorization time and a hash generated by including a specific logic plus the user's IP address. Upon completion the session data is encrypted with the secret key (MyAuth_SecretKey) and the according cookie is generated by Apache2::AuthCookie. All the following requests to the protected resource take the cookie (if exists) and the encrypted session key is validated (decrypted, the user is checked, the session time is checked for expiration and the hash is regenerated and compared with the provided one). Upon success the user is authorized to access the protected resource.

Should you require any additional information how the cookies logic works please check Apache2::AuthCookie documentation.

APACHE CONFIGURATION DIRECTIVES

All the configuration directives as used in the following format:

    PerlSetVar "AuthName""DirectiveName"

So if your have:

    <Directory /var/www/mysite/protected>
        AuthType Apache2::AuthCookieLDAP
        AuthName WhateverAuthName
    ...

Then the directive name for you will be (for instance):

    PerlSetVar WhatEverAuthName_SecretKey

MyAuth_SecretKey

Use your own secret key !!!DONT USE THE ONE FROM THE EXAMPLE!!!

MyAuth_SessionLifetime [optional, default: 00-24-00-00]

Format is: days-hours-minutes-seconds or 'forever' for endless sessions

MyAuth_LDAPURI

Your LDAP server URI

Format: ldap://127.0.0.1 or ldap://myldaphost

Use ldaps:// for secure connections (if your LDAP server supports it)

MyAuth_Base

LDAP Base. Please note that '%USER%' macro is substituted in the request with a username that is being authenticated.

Example: uid=%USER%,ou=staff,dc=company,dc=com

MyAuth_BindDN [optional]

Use the option if your LDAP does not accept anonymous bind for search.

Example: cn=ldap,dc=company,dc=com

MyAuth_BindPW [optional]

If you BindDN then you most likely want to specify a password here to bind with.

MyAuth_Cipher [optinal, default: 'des']

An encryption method used for the session key.

Supported methods: 'des', 'idea', 'blowfish', 'blowfish_pp'

MyAuth_Filter [optinal, default: '(uid=%USER%)']

You can additionally check if a user belongs to a specific group or has specific LDAP attributes. Where '%USER%' macro is substituted in the request with a username that is being authenticated.

For instance: (&(uid=%USER%)(objectClass=posixAccount))

perldoc Net::LDAP::Filter for additional info

MyAuth_DebugLogLevel [optional, default: 'alert']

A log level that will be used to send debug messages into your Apache log file.

Supported levels: 'emerg', 'alert', 'crit', 'err', 'warn', 'notice', 'info', 'debug'

MyAuth_ErrorLogLevel [optional, default: 'err']

A log level that will be used to send error messages into your Apache log file.

Supported levels: 'emerg', 'alert', 'crit', 'err', 'warn', 'notice', 'info', 'debug'

NOTE: In case of misconfiguration or your LDAP access unaviability the errors will not cause Apache to fall with the 500 error but you will not be able to login instead. Please check your log file to trace and fix such issues/misconfiguration.

MyAuth_Debug [optional, default: '0']

Set the option to '1' if you expect to see debug messages from the module in your Apache log file.

NOTE: It is also possible to fetch Base/BindDN/BindPW from a file(s)

Use the following syntax for that:

Example:

PerlSetVar MyAuth_Base file:/etc/ldap_base.conf:^\s*base\s+(.+)\r*\n$

PerlSetVar MyAuth_BindDN file:/etc/pam_ldap.conf:^\s*binddn\s+(.+)\r*\n$

PerlSetVar MyAuth_BindPW file:/etc/pam_ldap.conf:^\s*bindpw\s+(.+)\r*\n$

Format: "file:<filename>:<regular expression>" Where $1 will be the variable.

CLASS METHODS

cipher($r)

Returns a cipher for the encyption method specified in the corresponding apache config directive.

config($r, $req_key)

Returns a value for the specified $req_key.

ldap($r)

Returns Net::LDAP handler or NULL if there were errors.

ldap_search($r, $user)

Performs Net::LDAP->search(base => $base, scope => 'base', filter => $filter) and returns '1' if the specified $user is found or otherwise '0'.

ldap_check_user($r, $user, $password)

Performs Net::LDAP->bind($base, password => $password).

(%USER% is replaced by $user in $base)

rlog($r, $msg)

Logs $msg using $r->log_rerror and the current debug log level.

fatal($r, $msg)

Logs $msg using $r->log_rerror and the current error log level.

encode_string($r, $msg)

Encodes the specified string into a hex string.

decode_string($r, $msg)

Decodes the specified hex string and returns a string.

create_hash($r, $str)

Generates and returns a hash from the provided string.

encrypt_session($r, $str)

Encrypts $str and returns the provided session string.

decrypt_session($r, $str)

Decrypts $str and returns the provided encrypted session string.

check_expire_time($r, $session_time)

Checks the provided session time (unixtime) with the current time and returns '0' if the session time is still valid or '1' if passed.

authen_cred($r, $user, $password, @extra_data)

This is the overridden method of Apache::AuthCookie and is used to authenticate $user with the provided $password

Returns the encrypted session key in case of successfull authentication.

Please follow to Apache2::AuthCookie if you need more information about the method.

authen_ses_key($r, $session_key)

This is the overridden method of Apache::AuthCookie and is used to validate the provided $session_key.

Returns the authenticated username in case of success or redirects to the login page otherwise.

Please follow to Apache2::AuthCookie if you need more information about the method.

SUBCLASSING

You can subclass the module and override any of the available methods.

CREDITS

"SecretKey", "Lifetime" Apache config directive names and their definition style are similar to Apache2::AuthCookieDBI to keep it common for those who use both of the modules.

Authors of Apache2::AuthCookieDBI

Authors of Apache2::AuthCookie

COPYRIGHT

Copyright (C) 2013 Kirill Solomko

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

BUGS

Please report any bugs or feature requests through the web interface at: http://rt.cpan.org/Public/Dist/Display.html?Name=Apache2-AuthCookieLDAP

TODO

Add package tests.

SEE ALSO

perl(1), Apache2::AuthCookie, Apache2::AuthCookieDBI

cpanm Apache2::AuthCookieLDAP

perl -MCPAN -e shell
install Apache2::AuthCookieLDAP