Programming LDAP with Perl
Net::LDAP
Nick Urbanik <nicku@vtc.edu.hk>
Copyright Conditions: Open Publication License (see http://www.opencontent.org/openpub/)
Department of Information and Communications Technology

SNM — ver. 1.3

Network Directories and their Structure - p. 1/19

What is Net::LDAP?
I I

Mature and fully-featured Perl library Pure Perl; very easy to install on any platform N On Windows, do
D:\>ppm PPM - Programmer’s Package Manager version 3.1. Copyright (c) 2001 ActiveState SRL. All Rights Reserved. ... ppm> install perl-ldap

Introduction to Net::LDAP What is Net::LDAP? Net::LDAP Operations Encryption

I

I

On other platforms, do: $ sudo perl -MCPAN -e ’install Net::LDAP’ Excellent documentation N Start with $ perldoc Net::LDAP Helpful mailing list
N

SNM — ver. 1.3

Network Directories and their Structure - p. 2/19

Connecting
I

I

Connect when construct the Net::LDAP object: my $ldap = Net::LDAP->new( $hostname ) or die "Unable to connect to $hostname: $!"; See perldoc Net::LDAP for many other parameters you can pass in constructor

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 3/19

Authentication
I I I

I

The bind operation Three types: anonymous, simple, SASL Anonymous: my $result = $ldap->bind; Simple: my $result = $ldap->bind( $dn, password => $password ); N Danger! Password sent in clear text unless use TLS (see slide §18)

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 4/19

Return Values
I

I I I

Most Net::LDAP methods return an object N returned object provides method to obtain results of operation result code returned by $result->code error message returned by $result->error Example: warn $result->error if $result->code;

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 5/19

Searching
I

I

Need three things for a search: N search base, scope and filter my $result = $ldap->search( base => ’dc=tyict,dc=vtc,dc=edu,dc=hk’, scope => ’sub’, filter => ’(uid=nicku)’ ); die $result->error if $result->code; The result also contains the matching entries: foreach my $entry ( $result->entries ) { $entry->dump; } N Methods of the object that results from a search documented in perldoc Net::LDAP::Search

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 6/19

Entry Object
I

I I

Entry object is used: N to create new entries and N is available from a search Documented in perldoc Net::LDAP::Entry Methods: dn returns the DN for the entry: my $dn = $entry->dn; exists tests if an attribute exists in the entry: do_something() if $entry->exists( ’cn’ );

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 7/19

Entry Object — 2
I

Methods: get value obtain the value(s) for an attribute in the entry my $value = $entry->get_value( ’cn’ ); Multivalued attributes: Some attributes have more than one value. For these, get_value returns the first value in a scalar context, and all of them in a list context:
attributes returns a list of attributes the entry contains my @attrs = $entry->attributes;
my $first = $entry->get_value( ’objectClass’ ); my @values = $entry->get_value( ’objectClass’ );

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 8/19

Displaying an Entry
I

If all attributes can be printed, then this function could display an entry:
sub display_entry { my $entry = shift; my @attrs = $entry->attributes;

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries

Adding Entries foreach my $attr ( @attrs ) { Deleting an Entry Modifying an Entry my @value = $entry->get_value( $attr );Modify —
add

Modify — delete

}

}

foreach my $value ( @value ) { print "$attr: $value\n"; }

Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 9/19

Controlling What’s Returned
I

I

I

I

By default, LDAP server returns attributes and their values for each entry. Can ask server for just the types; then value returned for each attribute is empty: my $r = $ldap->search( base => ’dc=tyict,dc=vtc,dc=edu,dc=hk’, filter => ’(cn=Nick*)’, typesonly => 1, ); Access control limits what attributes are returned; can limit further by specifying a list of required attributes: my $r = $ldap->search( base => ’dc=tyict,dc=vtc,dc=edu,dc=hk’, filter => ’(cn=Nick*)’, attrs => [ qw(uid cn) ], ); Can test for specific attributes by asking for typesonly as well as specifying an attribute list.

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 10/19

Adding New Entries
I

Net::LDAP supports four ways of adding new entries to a directory: N the add method; N the Entry class; N LDIF: Same as adding with the Entry class, except Entry is read from a file via the LDIF module N DSML: Same as adding with the Entry class, except Entry is read from a file via the DSML module

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 11/19

Adding Entries
I

Pass an array reference of attribute and value pairs to the add method:
my $r = $ldap->add( $dn, attrs => [ cn => ’HP5000-A204e’, objectClass => [ qw/device ieee802Device/ ], description => ’Printer in A204e’, ], );

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

I

. . . or, create an Entry object and call the update method:
my $dn = ’ou=devices,dc=tyict,dc=vtc,dc=edu,dc=hk’; my $entry = Net::LDAP::Entry->new; $entry->dn( $dn ); $entry->add( cn => ’HP5000-A204e’ ); $entry->add( objectClass => ’device’, description => ’Printer in A204e’, ); $mesg = $entry->update( $ldap );

SNM — ver. 1.3

Network Directories and their Structure - p. 12/19

Deleting an Entry
I

I

Can delete an entry by passing a DN: my $dn = ’ou=dev,dc=tyict,dc=vtc,dc=edu,dc=hk’; my $r = $ldap->delete( $dn ); . . . or like many Net::LDAP methods, you can pass an entry where a DN is expected: $entry = find_entry_to_delete(); $r = $ldap->delete( $entry );

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Displaying an Entry Limit Returns Adding New Entries Adding Entries

Entry Object — 2

Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 13/19

Modifying an Entry
I

modify operation has four sub-operations: add N add new attributes N add values to existing multivalued attributes delete N delete whole attributes N delete values from within existing attributes replace replace attributes or add if necessary moddn rename an entry under same or different parent

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 14/19

Modify — add
I

Add a new attribute, or a new value to an existing multi-valued attribute:
$r = $ldap->modify( $dn, add => { mail => ’nicku@vtc.edu.hk’ } );

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

I

An error is returned if: N the attribute exists and is not multi-valued; N the attribute exists and is multi-valued and the value already exists; N the schema does not allow the attribute.

SNM — ver. 1.3

Network Directories and their Structure - p. 15/19

Modify — delete
I

I

To delete all instances of the attribute in the entry: $r = $ldap->modify( $dn, delete => [ ’mail’ ] ); You can delete specific values: $r = $ldap->modify( $dn, delete => { ’mail’ => [ ’nicku@abc.com’ ] } );

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry

Entry Object — 2

Modifying an Entry Modify — add

Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 16/19

Modify — replace
I

I

Replace whole attributes: $r = $ldap->modify( $dn, replace => { ’mail’ => ’nicku@xyz.com’ } ); Multi-valued: $r = $ldap->modify( $dn, replace => { ’mail’ => [ qw(nicku@xyz.com nick@iohk.com) ] } );

Introduction to Net::LDAP Net::LDAP Operations Connecting Authentication Return Values Searching Entry Object Entry Object — 2 Displaying an Entry Limit Returns Adding New Entries Adding Entries Deleting an Entry Modifying an Entry Modify — add Modify — delete Modify — replace Encryption

SNM — ver. 1.3

Network Directories and their Structure - p. 17/19

Using Start TLS
I LDAPv3 I

I

I

I

supports the Start TLS extension Allows a client to request that the server begin encrypting traffic with client Essential when using simple authentication; avoid password being sent in clear text over the network Here is the simplest use, where there is no requirement to store local copies of the certificates, but the identity of the server is not checked: my $r = $ldap->start_tls( verify => ’none’ ); See perldoc Net::LDAP and perldoc Net::LDAP::Security for details and examples.

Introduction to Net::LDAP Net::LDAP Operations Encryption Using Start TLS References

SNM — ver. 1.3

Network Directories and their Structure - p. 18/19

References
I See the excellent documentation with Net::LDAP:
Net::LDAP Net::LDAP::Constant Net::LDAP::Control Net::LDAP::Control::Paged Net::LDAP::Control::ProxyAuth Net::LDAP::Control::Sort Net::LDAP::Control::SortResult Net::LDAP::Control::VLV Net::LDAP::Control::VLVResponse Net::LDAP::DSML Net::LDAP::Entry Net::LDAP::Examples Net::LDAP::Extra Net::LDAP::FAQ Net::LDAP::Filter Net::LDAPI Net::LDAP::LDIF Net::LDAP::Message Net::LDAP::Reference Net::LDAP::RFC Net::LDAP::RootDSE Net::LDAPS Net::LDAP::Schema Net::LDAP::Search Net::LDAP::Security Net::LDAP::Util
Introduction to Net::LDAP Net::LDAP Operations Encryption Using Start TLS References

I See the web site for Net::LDAP: http://ldap.perl.org/ I Graham Barr wrote slides on which these notes are based:

http://ldap.perl.org/perl-ldap-oscon2001.pdf
I David N. Blank-Edelman, Perl for System Administration, O’Reilly, July

2000, ISBN: 1565926099.

I Gerald Carter, LDAP System Administration, O’Reilly, March 2003, ISBN:

1565924916.

I Clayton Donley, LDAP Programming, Management and Integration,
SNM — ver. 1.3

Manning, 2003, ISBN: 1930110405.

Network Directories and their Structure - p. 19/19