[catagits/Catalyst-Authentication-Store-LDAP.git] / README

NAME
    Catalyst::Authentication::Store::LDAP - Authentication from an LDAP
    Directory.

SYNOPSIS
        use Catalyst qw(
          Authentication
          );

        __PACKAGE__->config(
          'authentication' => {
             default_realm => "ldap",
             realms => {
               ldap => {
                 credential => {
                   class => "Password",
                   password_field => "password",
                   password_type => "self_check",
                 },
                 store => {
                   binddn              => "anonymous",
                   bindpw              => "dontcarehow",
                   class               => "LDAP",
                   ldap_server         => "ldap.yourcompany.com",
                   ldap_server_options => { timeout => 30 },
                   role_basedn         => "ou=groups,ou=OxObjects,dc=yourcompany,dc=com",
                   role_field          => "uid",
                   role_filter         => "(&(objectClass=posixGroup)(memberUid=%s))",
                   role_scope          => "one",
                   role_search_options => { deref => "always" },
                   role_value          => "dn",
                   role_search_as_user => 0,
                   start_tls           => 1,
                   start_tls_options   => { verify => "none" },
                   entry_class         => "MyApp::LDAP::Entry",
                   use_roles           => 1,
                   user_basedn         => "ou=people,dc=yourcompany,dc=com",
                   user_field          => "uid",
                   user_filter         => "(&(objectClass=posixAccount)(uid=%s))",
                   user_scope          => "one", # or "sub" for Active Directory
                   user_search_options => {
                     deref => 'always',
                     attrs => [qw( distinguishedname name mail )],
                   },
                   user_results_filter => sub { return shift->pop_entry },
                 },
               },
             },
           },
        );

        sub login : Global {
            my ( $self, $c ) = @_;

            $c->authenticate({
                              id          => $c->req->param("login"),
                              password    => $c->req->param("password")
                             });
            $c->res->body("Welcome " . $c->user->username . "!");
        }

DESCRIPTION
    This plugin implements the Catalyst::Authentication v.10 API. Read that
    documentation first if you are upgrading from a previous version of this
    plugin.

    This plugin uses "Net::LDAP" to let your application authenticate
    against an LDAP directory. It has a pretty high degree of flexibility,
    given the wide variation of LDAP directories and schemas from one system
    to another.

    It authenticates users in two steps:

    1) A search of the directory is performed, looking for a user object
    that matches the username you pass. This is done with the bind
    credentials supplied in the "binddn" and "bindpw" configuration options.

    2) If that object is found, we then re-bind to the directory as that
    object. Assuming this is successful, the user is Authenticated.

CONFIGURATION OPTIONS
  Configuring with YAML
    Set Configuration to be loaded via Config.yml in YourApp.pm

        use YAML qw(LoadFile);
        use Path::Class 'file';

        __PACKAGE__->config(
            LoadFile(
                file(__PACKAGE__->config->{home}, 'Config.yml')
            )
        );

    Settings in Config.yml (adapt these to whatever configuration format you
    use):

        # Config for Store::LDAP
        authentication:
            default_realm: ldap
            realms:
                ldap:
                    credential:
                        class: Password
                        password_field: password
                        password_type:  self_check
                    store:
                        class: LDAP
                        ldap_server: ldap.yourcompany.com
                        ldap_server_options:
                            timeout: 30
                        binddn: anonymous
                        bindpw: dontcarehow
                        start_tls: 1
                        start_tls_options:
                            verify: none
                        user_basedn: ou=people,dc=yourcompany,dc=com
                        user_filter: (&(objectClass=posixAccount)(uid=%s))
                        user_scope: one
                        user_field: uid
                        user_search_options:
                            deref: always
                        use_roles: 1
                        role_basedn: ou=groups,ou=OxObjects,dc=yourcompany,dc=com
                        role_filter: (&(objectClass=posixGroup)(memberUid=%s))
                        role_scope: one
                        role_field: uid
                        role_value: dn
                        role_search_options:
                            deref: always

    NOTE: The settings above reflect the default values for OpenLDAP. If you
    are using Active Directory instead, Matija Grabnar suggests that the
    following tweeks to the example configuration will work:

        user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
        user_field:  samaccountname
        user_filter: (sAMAccountName=%s)
        user_scope: sub

    He also notes: "I found the case in the value of user_field to be
    significant: it didn't seem to work when I had the mixed case value
    there."

  ldap_server
    This should be the hostname of your LDAP server.

  ldap_server_options
    This should be a hashref containing options to pass to Net::LDAP->new().
    See Net::LDAP for the full list.

  binddn
    This should be the DN of the object you wish to bind to the directory as
    during the first phase of authentication. (The user lookup phase)

    If you supply the value "anonymous" to this option, we will bind
    anonymously to the directory. This is the default.

  bindpw
    This is the password for the initial bind.

  start_tls
    If this is set to 1, we will convert the LDAP connection to use SSL.

  start_tls_options
    This is a hashref, which contains the arguments to the Net::LDAP
    start_tls method. See Net::LDAP for the complete list of options.

  user_basedn
    This is the basedn for the initial user lookup. Usually points to the
    top of your "users" branch; ie "ou=people,dc=yourcompany,dc=com".

  user_filter
    This is the LDAP Search filter used during user lookup. The special
    string '%s' will be replaced with the username you pass to $c->login. By
    default it is set to '(uid=%s)'. Other possibly useful filters:

        (&(objectClass=posixAccount)(uid=%s))
        (&(objectClass=User)(cn=%s))

  user_scope
    This specifies the scope of the search for the initial user lookup.
    Valid values are "base", "one", and "sub". Defaults to "sub".

  user_field
    This is the attribute of the returned LDAP object we will use for their
    "username". This defaults to "uid". If you had user_filter set to:

        (&(objectClass=User)(cn=%s))

    You would probably set this to "cn". You can also set it to an array, to
    allow more than one login field. The first field will be returned as
    identifier for the user.

  user_search_options
    This takes a hashref. It will append it's values to the call to
    Net::LDAP's "search" method during the initial user lookup. See
    Net::LDAP for valid options.

    Be careful not to specify:

        filter
        scope
        base

    As they are already taken care of by other configuration options.

  user_results_filter
    This is a Perl CODE ref that can be used to filter out multiple results
    from your LDAP query. In theory, your LDAP query should only return one
    result and find_user() will throw an exception if it encounters more
    than one result. However, if you have, for whatever reason, a legitimate
    reason for returning multiple search results from your LDAP query, use
    "user_results_filter" to filter out the LDAP entries you do not want
    considered. Your CODE ref should expect a single argument, a
    Net::LDAP::Search object, and it should return exactly one value, a
    Net::LDAP::Entry object.

    Example:

     user_results_filter => sub {
                              my $search_obj = shift;
                              foreach my $entry ($search_obj->entries) {
                                  return $entry if my_match_logic( $entry );
                              }
                              return undef; # i.e., no match
                            }

  use_roles
    Whether or not to enable role lookups. It defaults to true; set it to 0
    if you want to always avoid role lookups.

  role_basedn
    This should be the basedn where the LDAP Objects representing your roles
    are.

  role_filter
    This should be the LDAP Search filter to use during the role lookup. It
    defaults to '(memberUid=%s)'. The %s in this filter is replaced with the
    value of the "role_value" configuration option.

    So, if you had a role_value of "cn", then this would be populated with
    the cn of the User's LDAP object. The special case is a role_value of
    "dn", which will be replaced with the User's DN.

  role_scope
    This specifies the scope of the search for the user's role lookup. Valid
    values are "base", "one", and "sub". Defaults to "sub".

  role_field
    Should be set to the Attribute of the Role Object's returned during Role
    lookup you want to use as the "name" of the role. Defaults to "CN".

  role_value
    This is the attribute of the User object we want to use in our
    role_filter. If this is set to "dn", we will use the User Objects DN.

  role_search_options
    This takes a hashref. It will append it's values to the call to
    Net::LDAP's "search" method during the user's role lookup. See Net::LDAP
    for valid options.

    Be careful not to specify:

        filter
        scope
        base

    As they are already taken care of by other configuration options.

  role_search_as_user
    By default this setting is false, and the role search will be performed
    by binding to the directory with the details in the *binddn* and
    *bindpw* fields. If this is set to false, then the role search will
    instead be performed when bound as the user you authenticated as.

  entry_class
    The name of the class of LDAP entries returned. This class should exist
    and is expected to be a subclass of Net::LDAP::Entry

  user_class
    The name of the class of user object returned. By default, this is
    Catalyst::Authentication::Store::LDAP::User.

METHODS
  new
    This method will populate "default_auth_store" in
    Catalyst::Plugin::Authentication with this object.

AUTHORS
    Adam Jacob <holoway@cpan.org>

    Some parts stolen shamelessly and entirely from
    Catalyst::Plugin::Authentication::Store::Htpasswd.

    Currently maintained by Peter Karman <karman@cpan.org>.

THANKS
    To nothingmuch, ghenry, castaway and the rest of #catalyst for the help.
    :)

SEE ALSO
    Catalyst::Authentication::Store::LDAP,
    Catalyst::Authentication::Store::LDAP::User,
    Catalyst::Authentication::Store::LDAP::Backend,
    Catalyst::Plugin::Authentication, Net::LDAP

COPYRIGHT & LICENSE
    Copyright (c) 2005 the aforementioned authors. All rights reserved. This
    program is free software; you can redistribute it and/or modify it under
    the same terms as Perl itself.
Commit	Line	Data
a93dbce7	1	NAME
	2	Catalyst::Authentication::Store::LDAP - Authentication from an LDAP
	3	Directory.
fa35fd6f	4
a93dbce7	5	SYNOPSIS
	6	use Catalyst qw(
	7	Authentication
	8	);
fa35fd6f	9
a93dbce7	10	__PACKAGE__->config(
	11	'authentication' => {
	12	default_realm => "ldap",
	13	realms => {
	14	ldap => {
	15	credential => {
	16	class => "Password",
	17	password_field => "password",
	18	password_type => "self_check",
	19	},
	20	store => {
	21	binddn => "anonymous",
	22	bindpw => "dontcarehow",
	23	class => "LDAP",
	24	ldap_server => "ldap.yourcompany.com",
	25	ldap_server_options => { timeout => 30 },
	26	role_basedn => "ou=groups,ou=OxObjects,dc=yourcompany,dc=com",
	27	role_field => "uid",
	28	role_filter => "(&(objectClass=posixGroup)(memberUid=%s))",
	29	role_scope => "one",
	30	role_search_options => { deref => "always" },
	31	role_value => "dn",
	32	role_search_as_user => 0,
	33	start_tls => 1,
	34	start_tls_options => { verify => "none" },
	35	entry_class => "MyApp::LDAP::Entry",
	36	use_roles => 1,
	37	user_basedn => "ou=people,dc=yourcompany,dc=com",
	38	user_field => "uid",
	39	user_filter => "(&(objectClass=posixAccount)(uid=%s))",
57d476f1	40	user_scope => "one", # or "sub" for Active Directory
58b695ab	41	user_search_options => {
	42	deref => 'always',
	43	attrs => [qw( distinguishedname name mail )],
	44	},
a93dbce7	45	user_results_filter => sub { return shift->pop_entry },
	46	},
	47	},
	48	},
	49	},
	50	);
fa35fd6f	51
a93dbce7	52	sub login : Global {
a93dbce7	53	my ( $self, $c ) = @_;
fa35fd6f	54
a93dbce7	55	$c->authenticate({
58b695ab	56	id => $c->req->param("login"),
58b695ab	57	password => $c->req->param("password")
a93dbce7	58	});
	59	$c->res->body("Welcome " . $c->user->username . "!");
	60	}
fa35fd6f	61
a93dbce7	62	DESCRIPTION
	63	This plugin implements the Catalyst::Authentication v.10 API. Read that
	64	documentation first if you are upgrading from a previous version of this
	65	plugin.
fa35fd6f	66
a93dbce7	67	This plugin uses "Net::LDAP" to let your application authenticate
	68	against an LDAP directory. It has a pretty high degree of flexibility,
	69	given the wide variation of LDAP directories and schemas from one system
	70	to another.
fa35fd6f	71
a93dbce7	72	It authenticates users in two steps:
fa35fd6f	73
a93dbce7	74	1) A search of the directory is performed, looking for a user object
	75	that matches the username you pass. This is done with the bind
	76	credentials supplied in the "binddn" and "bindpw" configuration options.
fa35fd6f	77
a93dbce7	78	2) If that object is found, we then re-bind to the directory as that
a93dbce7	79	object. Assuming this is successful, the user is Authenticated.
fa35fd6f	80
a93dbce7	81	CONFIGURATION OPTIONS
	82	Configuring with YAML
	83	Set Configuration to be loaded via Config.yml in YourApp.pm
fa35fd6f	84
a93dbce7	85	use YAML qw(LoadFile);
a93dbce7	86	use Path::Class 'file';
fa35fd6f	87
a93dbce7	88	__PACKAGE__->config(
	89	LoadFile(
	90	file(__PACKAGE__->config->{home}, 'Config.yml')
	91	)
	92	);
fa35fd6f	93
a93dbce7	94	Settings in Config.yml (adapt these to whatever configuration format you
a93dbce7	95	use):
fa35fd6f	96
a93dbce7	97	# Config for Store::LDAP
	98	authentication:
	99	default_realm: ldap
	100	realms:
	101	ldap:
	102	credential:
	103	class: Password
	104	password_field: password
	105	password_type: self_check
	106	store:
	107	class: LDAP
	108	ldap_server: ldap.yourcompany.com
	109	ldap_server_options:
	110	timeout: 30
	111	binddn: anonymous
	112	bindpw: dontcarehow
	113	start_tls: 1
	114	start_tls_options:
	115	verify: none
	116	user_basedn: ou=people,dc=yourcompany,dc=com
	117	user_filter: (&(objectClass=posixAccount)(uid=%s))
	118	user_scope: one
	119	user_field: uid
	120	user_search_options:
	121	deref: always
	122	use_roles: 1
	123	role_basedn: ou=groups,ou=OxObjects,dc=yourcompany,dc=com
	124	role_filter: (&(objectClass=posixGroup)(memberUid=%s))
	125	role_scope: one
	126	role_field: uid
	127	role_value: dn
	128	role_search_options:
	129	deref: always
	130
	131	NOTE: The settings above reflect the default values for OpenLDAP. If you
	132	are using Active Directory instead, Matija Grabnar suggests that the
	133	following tweeks to the example configuration will work:
	134
	135	user_basedn: ou=Domain Users,ou=Accounts,dc=mycompany,dc=com
	136	user_field: samaccountname
58b695ab	137	user_filter: (sAMAccountName=%s)
57d476f1	138	user_scope: sub
a93dbce7	139
	140	He also notes: "I found the case in the value of user_field to be
	141	significant: it didn't seem to work when I had the mixed case value
	142	there."
	143
	144	ldap_server
	145	This should be the hostname of your LDAP server.
	146
	147	ldap_server_options
	148	This should be a hashref containing options to pass to Net::LDAP->new().
	149	See Net::LDAP for the full list.
	150
	151	binddn
	152	This should be the DN of the object you wish to bind to the directory as
	153	during the first phase of authentication. (The user lookup phase)
	154
	155	If you supply the value "anonymous" to this option, we will bind
	156	anonymously to the directory. This is the default.
	157
	158	bindpw
	159	This is the password for the initial bind.
	160
	161	start_tls
	162	If this is set to 1, we will convert the LDAP connection to use SSL.
	163
	164	start_tls_options
	165	This is a hashref, which contains the arguments to the Net::LDAP
	166	start_tls method. See Net::LDAP for the complete list of options.
	167
	168	user_basedn
	169	This is the basedn for the initial user lookup. Usually points to the
	170	top of your "users" branch; ie "ou=people,dc=yourcompany,dc=com".
	171
	172	user_filter
	173	This is the LDAP Search filter used during user lookup. The special
	174	string '%s' will be replaced with the username you pass to $c->login. By
	175	default it is set to '(uid=%s)'. Other possibly useful filters:
	176
	177	(&(objectClass=posixAccount)(uid=%s))
	178	(&(objectClass=User)(cn=%s))
	179
	180	user_scope
	181	This specifies the scope of the search for the initial user lookup.
	182	Valid values are "base", "one", and "sub". Defaults to "sub".
	183
	184	user_field
	185	This is the attribute of the returned LDAP object we will use for their
	186	"username". This defaults to "uid". If you had user_filter set to:
	187
	188	(&(objectClass=User)(cn=%s))
	189
	190	You would probably set this to "cn". You can also set it to an array, to
	191	allow more than one login field. The first field will be returned as
	192	identifier for the user.
	193
	194	user_search_options
	195	This takes a hashref. It will append it's values to the call to
	196	Net::LDAP's "search" method during the initial user lookup. See
	197	Net::LDAP for valid options.
	198
	199	Be careful not to specify:
	200
	201	filter
	202	scope
203	base
204
205	As they are already taken care of by other configuration options.
206
207	user_results_filter
208	This is a Perl CODE ref that can be used to filter out multiple results
209	from your LDAP query. In theory, your LDAP query should only return one
210	result and find_user() will throw an exception if it encounters more
211	than one result. However, if you have, for whatever reason, a legitimate
212	reason for returning multiple search results from your LDAP query, use
213	"user_results_filter" to filter out the LDAP entries you do not want
214	considered. Your CODE ref should expect a single argument, a
215	Net::LDAP::Search object, and it should return exactly one value, a
216	Net::LDAP::Entry object.
217
218	Example:
219
220	user_results_filter => sub {
221	my $search_obj = shift;
222	foreach my $entry ($search_obj->entries) {
223	return $entry if my_match_logic( $entry );
224	}
225	return undef; # i.e., no match
226	}
934094a2	227
a93dbce7	228	use_roles
	229	Whether or not to enable role lookups. It defaults to true; set it to 0
	230	if you want to always avoid role lookups.
	231
	232	role_basedn
	233	This should be the basedn where the LDAP Objects representing your roles
	234	are.
	235
	236	role_filter
	237	This should be the LDAP Search filter to use during the role lookup. It
	238	defaults to '(memberUid=%s)'. The %s in this filter is replaced with the
	239	value of the "role_value" configuration option.
	240
	241	So, if you had a role_value of "cn", then this would be populated with
	242	the cn of the User's LDAP object. The special case is a role_value of
	243	"dn", which will be replaced with the User's DN.
	244
	245	role_scope
	246	This specifies the scope of the search for the user's role lookup. Valid
	247	values are "base", "one", and "sub". Defaults to "sub".
	248
	249	role_field
	250	Should be set to the Attribute of the Role Object's returned during Role
	251	lookup you want to use as the "name" of the role. Defaults to "CN".
	252
	253	role_value
	254	This is the attribute of the User object we want to use in our
	255	role_filter. If this is set to "dn", we will use the User Objects DN.
	256
	257	role_search_options
	258	This takes a hashref. It will append it's values to the call to
	259	Net::LDAP's "search" method during the user's role lookup. See Net::LDAP
	260	for valid options.
	261
	262	Be careful not to specify:
	263
	264	filter
	265	scope
	266	base
	267
	268	As they are already taken care of by other configuration options.
	269
	270	role_search_as_user
	271	By default this setting is false, and the role search will be performed
	272	by binding to the directory with the details in the binddn and
	273	bindpw fields. If this is set to false, then the role search will
	274	instead be performed when bound as the user you authenticated as.
	275
	276	entry_class
	277	The name of the class of LDAP entries returned. This class should exist
	278	and is expected to be a subclass of Net::LDAP::Entry
	279
	280	user_class
	281	The name of the class of user object returned. By default, this is
	282	Catalyst::Authentication::Store::LDAP::User.
	283
	284	METHODS
	285	new
	286	This method will populate "default_auth_store" in
	287	Catalyst::Plugin::Authentication with this object.
	288
	289	AUTHORS
	290	Adam Jacob <holoway@cpan.org>
	291
292	Some parts stolen shamelessly and entirely from
293	Catalyst::Plugin::Authentication::Store::Htpasswd.
294
295	Currently maintained by Peter Karman <karman@cpan.org>.
296
297	THANKS
298	To nothingmuch, ghenry, castaway and the rest of #catalyst for the help.
299	:)
300
301	SEE ALSO
302	Catalyst::Authentication::Store::LDAP,
303	Catalyst::Authentication::Store::LDAP::User,
304	Catalyst::Authentication::Store::LDAP::Backend,
305	Catalyst::Plugin::Authentication, Net::LDAP
306
307	COPYRIGHT & LICENSE
308	Copyright (c) 2005 the aforementioned authors. All rights reserved. This
309	program is free software; you can redistribute it and/or modify it under
310	the same terms as Perl itself.
fa35fd6f	311