[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 },
                   persist_in_session  => 'all',
                 },
               },
             },
           },
        );

        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 its 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 its 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.

  persist_in_session
    Can take one of the following values, defaults to "username":

    "username"
        Only store the username in the session and lookup the user and its
        roles on every request. That was how the module worked until version
        1.015 and is also the default for backwards compatibility.

    "all"
        Store the user object and its roles in the session and never look it
        up in the store after login.

        NOTE: It's recommended to limit the user attributes fetched from
        LDAP using "user_search_options" / "attrs" to not exhaust the
        session store.

  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> Peter Karman <karman@cpan.org> Alexander
    Hartmaier <abraxxa@cpan.org>

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

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