Ruby 简明教程

Ruby - LDAP Tutorial

Ruby/LDAP 是 Ruby 的一个扩展库。它提供了一些 LDAP 库的接口,如 OpenLDAP、UMich LDAP、Netscape SDK、ActiveDirectory。

应用程序开发的通用 API 在 RFC1823 中描述,并由 Ruby/LDAP 支持。

Ruby/LDAP Installation

您可以从 SOURCEFORGE.NET 下载并安装完整的 Ruby/LDAP 程序包。

在安装 Ruby/LDAP 之前,请确保您具有以下组件:

  1. Ruby 1.8.x(如果您想使用 ldap/control,则至少为 1.8.2)。

  2. OpenLDAP、Netscape SDK、Windows 2003 或 Windows XP。

现在,您可以使用标准 Ruby 安装方法。在开始之前,如果您想查看 extconf.rb 的可用选项,请使用“--help”选项运行它。

$ ruby extconf.rb [--with-openldap1|--with-openldap2| \
                   --with-netscape|--with-wldap32]
$ make
$ make install

NOTE − 如果您在 Windows 上构建软件,您可能需要使用 nmake 而不是 make。

Establish LDAP Connection

这是一个两步过程:

Step 1 − Create Connection Object

以下是创建与 LDAP 目录连接的语法。

LDAP::Conn.new(host = 'localhost', port = LDAP_PORT)
  1. host − 这是运行 LDAP 目录的主机 ID。我们将视其为本地主机。

  2. port − 这是用于 LDAP 服务的端口。标准 LDAP 端口为 636 和 389。请确保使用的是服务器上的哪个端口,否则可以使用 LDAP::LDAP_PORT。

此调用将返回与服务器、主机在端口 port 上的新 LDAP::Conn 连接。

Step 2 − Binding

这里是我们通常指定将在会话剩余部分中使用的用户名和密码。

以下是绑定一个 LDAP 连接的语法,使用 DN, dn ,凭据, pwd ,和绑定方法, method

conn.bind(dn = nil, password = nil, method = LDAP::LDAP_AUTH_SIMPLE)do
....
end

您可以使用相同的方法而没有代码块。在这种情况下,您需要如下显式解绑连接 −

conn.bind(dn = nil, password = nil, method = LDAP::LDAP_AUTH_SIMPLE)
....
conn.unbind

如果提供了代码块,则 self 被传递给该块。

我们现在可以在 bind 方法的块(bind 和 unbind 之间)中执行搜索、添加、修改或删除操作,前提是我们有适当的权限。

Example

假设我们正在本地服务器上工作,让我们将适当的主机、域、用户 ID 和密码等组合在一起。

#/usr/bin/ruby -w

require 'ldap'

$HOST =    'localhost'
$PORT =    LDAP::LDAP_PORT
$SSLPORT = LDAP::LDAPS_PORT

conn = LDAP::Conn.new($HOST, $PORT)
conn.bind('cn = root, dc = localhost, dc = localdomain','secret')
....
conn.unbind

Adding an LDAP Entry

添加 LDPA 条目是一个两步过程 −

Step 1 − Creating LDAP::Mod object

我们需要将 LDAP::Mod 对象传递给 conn.add 方法以创建条目。以下是创建 LDAP::Mod 对象的简单语法 −

Mod.new(mod_type, attr, vals)
  1. mod_type − 一个或多个选项 LDAP_MOD_ADD、LDAP_MOD_REPLACE 或 LDAP_MOD_DELETE。

  2. attr − 是要对其进行操作的属性的名称。

  3. vals − 是与 attr 相关的值的数组。如果 vals 包含二进制数据,应使用 LDAP_MOD_BVALUES 逻辑 OR’ed (|) 修饰 mod_type。

此调用返回 LDAP::Mod 对象,可以将其传递给 LDAP::Conn 类中的方法,例如 Conn#add、Conn#add_ext、Conn#modify 和 Conn#modify_ext。

Step 2 − Calling conn.add Method

一旦我们准备好 LDAP::Mod 对象,就可以调用 conn.add 方法来创建条目。下面是调用此方法的语法 −

conn.add(dn, attrs)

此方法添加了一个条目,带有 DN、dn 和属性 attrs。此处,attrs 应是 LDAP::Mod 对象的数组或属性/值数组对的哈希。

Example

下面是一个完整示例,它将创建两个目录条目 −

#/usr/bin/ruby -w

require 'ldap'

$HOST =    'localhost'
$PORT =    LDAP::LDAP_PORT
$SSLPORT = LDAP::LDAPS_PORT

conn = LDAP::Conn.new($HOST, $PORT)
conn.bind('cn = root, dc = localhost, dc = localdomain','secret')

conn.perror("bind")
entry1 = [
   LDAP.mod(LDAP::LDAP_MOD_ADD,'objectclass',['top','domain']),
   LDAP.mod(LDAP::LDAP_MOD_ADD,'o',['TTSKY.NET']),
   LDAP.mod(LDAP::LDAP_MOD_ADD,'dc',['localhost']),
]

entry2 = [
   LDAP.mod(LDAP::LDAP_MOD_ADD,'objectclass',['top','person']),
   LDAP.mod(LDAP::LDAP_MOD_ADD, 'cn', ['Zara Ali']),
   LDAP.mod(LDAP::LDAP_MOD_ADD | LDAP::LDAP_MOD_BVALUES, 'sn',
                     ['ttate','ALI', "zero\000zero"]),
]

begin
   conn.add("dc = localhost, dc = localdomain", entry1)
   conn.add("cn = Zara Ali, dc = localhost, dc =  localdomain", entry2)
rescue LDAP::ResultError
   conn.perror("add")
   exit
end
conn.perror("add")
conn.unbind

Modifying an LDAP Entry

修改条目类似于添加条目。只需使用属性调用 modify 方法来修改,而不是用 add。下面是 modify 方法的简单语法。

conn.modify(dn, mods)

此方法使用 DN、dn 和属性 mods 修改条目。此处,mods 应是 LDAP::Mod 对象的数组或属性/值数组对的哈希。

Example

为了修改上一节中添加的条目的姓氏,我们可以编写 −

#/usr/bin/ruby -w

require 'ldap'

$HOST =    'localhost'
$PORT =    LDAP::LDAP_PORT
$SSLPORT = LDAP::LDAPS_PORT

conn = LDAP::Conn.new($HOST, $PORT)
conn.bind('cn = root, dc = localhost, dc = localdomain','secret')

conn.perror("bind")
entry1 = [
   LDAP.mod(LDAP::LDAP_MOD_REPLACE, 'sn', ['Mohtashim']),
]

begin
   conn.modify("cn = Zara Ali, dc = localhost, dc = localdomain", entry1)
rescue LDAP::ResultError
   conn.perror("modify")
   exit
end
conn.perror("modify")
conn.unbind

Deleting an LDAP Entry

要删除条目,请使用 distinguished name 作为参数来调用 delete 方法。下面是 delete 方法的简单语法。

conn.delete(dn)

此方法使用 DN、dn 删除条目。

Example

要删除上一节中添加的 Zara Mohtashim 条目,我们可以编写 −

#/usr/bin/ruby -w

require 'ldap'

$HOST =    'localhost'
$PORT =    LDAP::LDAP_PORT
$SSLPORT = LDAP::LDAPS_PORT

conn = LDAP::Conn.new($HOST, $PORT)
conn.bind('cn = root, dc = localhost, dc = localdomain','secret')

conn.perror("bind")
begin
   conn.delete("cn = Zara-Mohtashim, dc = localhost, dc = localdomain")
rescue LDAP::ResultError
   conn.perror("delete")
   exit
end
conn.perror("delete")
conn.unbind

Modifying the Distinguished Name

无法使用 modify 方法修改条目的 distinguished name。可以使用 modrdn 方法来代替。以下是 modrdn 方法的简单语法 −

conn.modrdn(dn, new_rdn, delete_old_rdn)

此方法使用 DN、dn 修改条目的 RDN,为其提供新的 RDN、new_rdn。如果 delete_old_rdn 为 true,则旧的 RDN 值将从条目中删除。

Example

假设我们有以下条目 −

dn: cn = Zara Ali,dc = localhost,dc = localdomain
cn: Zara Ali
sn: Ali
objectclass: person

然后,我们可以使用以下代码修改它的 distinguished name −

#/usr/bin/ruby -w

require 'ldap'

$HOST =    'localhost'
$PORT =    LDAP::LDAP_PORT
$SSLPORT = LDAP::LDAPS_PORT

conn = LDAP::Conn.new($HOST, $PORT)
conn.bind('cn = root, dc = localhost, dc = localdomain','secret')

conn.perror("bind")
begin
   conn.modrdn("cn = Zara Ali, dc = localhost, dc = localdomain", "cn = Zara Mohtashim", true)
rescue LDAP::ResultError
   conn.perror("modrdn")
   exit
end
conn.perror("modrdn")
conn.unbind

要在 LDAP 目录中执行搜索,请使用包含三种不同搜索模式之一的 search 方法 −

  1. LDAP_SCOPE_BASEM − 仅搜索基本节点。

  2. LDAP_SCOPE_ONELEVEL - 搜索根节点的所有子项。

  3. LDAP_SCOPE_SUBTREE - 搜索包括根节点的整个子树。

Example

在这里,我们将搜索 cn = localhost,cn = localdomain 项的整个子树以查找人员对象 -

#/usr/bin/ruby -w

require 'ldap'

$HOST =    'localhost'
$PORT =    LDAP::LDAP_PORT
$SSLPORT = LDAP::LDAPS_PORT

base = 'dc = localhost,dc = localdomain'
scope = LDAP::LDAP_SCOPE_SUBTREE
filter = '(objectclass = person)'
attrs = ['sn', 'cn']

conn = LDAP::Conn.new($HOST, $PORT)
conn.bind('cn = root, dc = localhost, dc = localdomain','secret')

conn.perror("bind")
begin
   conn.search(base, scope, filter, attrs) { |entry|
      # print distinguished name
      p entry.dn
      # print all attribute names
      p entry.attrs
      # print values of attribute 'sn'
      p entry.vals('sn')
      # print entry as Hash
      p entry.to_hash
   }
rescue LDAP::ResultError
   conn.perror("search")
   exit
end
conn.perror("search")
conn.unbind

这会对每个匹配项调用提供的代码块,其中 LDAP 项由 LDAP::Entry 类的实例表示。使用 search 的最后一个参数,您可以指定感兴趣的属性,省略所有其他属性。如果您在这里传递 nil,则会返回所有属性,与关系数据库中的“SELECT *”相同。

LDAP::Entry 类的 dn 方法(get_dn 的别名)返回项的专有名称,使用 to_hash 方法,您可以获得其属性的哈希表示形式(包括专有名称)。若要获取项属性的列表,请使用 attrs 方法(get_attributes 的别名)。此外,要获取一个特定属性值的列表,请使用 vals 方法(get_values 的别名)。

Handling Errors

Ruby/LDAP 定义了两种不同的异常类 -

  1. 如果发生错误,则 new、bind 或 unbind 方法会引发 LDAP::Error 异常。

  2. 如果添加、修改、删除或搜索 LDAP 目录会引发 LDAP::ResultError。

Further Reading

有关 LDAP 方法的完整详细信息,请参阅 LDAP Documentation 的标准文档。