view release on metacpan or  search on metacpan

lib/Catalyst/Model/LDAP/Connection.pm  view on Meta::CPAN

Catalyst::Model::LDAP::Connection - Convenience methods for Net::LDAP

=head1 VERSION

version 0.21

=head1 DESCRIPTION

Subclass of L<Net::LDAP>, which adds paging support and an additional
method to rebless the entries.  See L<Catalyst::Model::LDAP::Entry>
for more information.

=head1 OVERRIDING METHODS

If you want to override methods provided by L<Net::LDAP>, you can use
the C<connection_class> configuration variable.  For example:

    # In lib/MyApp/Model/LDAP.pm
    package MyApp::Model::LDAP;
    use base qw/Catalyst::Model::LDAP/;

    __PACKAGE__->config(
        # ...
        connection_class => 'MyApp::LDAP::Connection',
    );

    1;

    # In lib/MyApp/LDAP/Connection.pm
    package MyApp::LDAP::Connection;
    use base qw/Catalyst::Model::LDAP::Connection/;
    use Authen::SASL;

    sub bind {
        my ($self, @args) = @_;

        my $sasl = Authen::SASL->new(...);
        push @args, sasl => $sasl;

        $self->SUPER::bind(@args);
    }

    1;

=head1 METHODS

=head2 new

Create a new connection to the specific LDAP server.

    my $conn = Catalyst::Model::LDAP::Connection->new(
        host => 'ldap.ufl.edu',
        base => 'ou=People,dc=ufl,dc=edu',
    );

On connection failure, an error is thrown using L<Carp/croak>.

=head2 bind

Bind to the configured LDAP server using the specified credentials.

    $conn->bind(
        dn       => 'uid=dwc,ou=People,dc=ufl,dc=edu',
        password => 'secret',
    );

This method behaves similarly to L<Net::LDAP/bind>, except that it
gives an explicit name to the C<dn> parameter.  For example, if you
need to use SASL to bind to the server, you can specify that in your
call:

    $conn->bind(
        dn   => 'uid=dwc,ou=People,dc=ufl,dc=edu',
        sasl => Authen::SASL->new(mechanism => 'GSSAPI'),
    );

Additionally, if the C<start_tls> configuration option is present, the
client will use L<Net::LDAP/start_tls> to make your connection secure.

For more information on customizing the bind process, see
L</OVERRIDING METHODS>.

=head2 search

Search the configured directory using a given filter.  For example:

    my $mesg = $c->model('Person')->search('(cn=Lou Rhodes)');
    my $entry = $mesg->shift_entry;
    print $entry->title;

This method overrides the C<search> method in L<Net::LDAP> to add
paging support.  The following additional options are supported:

=over 4

=item C<raw>

Use REGEX to denote the names of attributes that are to be considered binary
in search results.

When this option is given, Net::LDAP converts all values of attributes B<not>
matching this REGEX into Perl UTF-8 strings so that the regular Perl operators
(pattern matching, ...) can operate as one expects even on strings with
international characters.

If this option is not given, attribute values are treated as byte strings.

Generally, you'll only ever need to do this if using RFC'd LDAP attributes
and not a custom LDAP schema:

    raw => qr/(?i:^jpegPhoto|;binary)/,

=item C<authz>

This allows you to use LDAPv3 Proxy Authorization control object, i.e.
(L<Net::LDAP::Control::ProxyAuth>):

    authz => 'uid=gavinhenry,ou=users,dc=surevoip,dc=co,dc=uk',

=item C<page>