activeldap 1.2.4 → 3.1.0

data/doc/text/rails.textile

@@ -0,0 +1,144 @@
+h1. Rails
+
+ActiveLdap supports Rails 3.1.
+
+h2. Install
+
+To install, simply add the following code to your Gemfile:
+
+<pre>
+gem 'activeldap'
+</pre>
+
+You should also depend on an LDAP adapter such as Net::LDAP
+or Ruby/LDAP. The following example uses Ruby/LDAP:
+
+<pre>
+gem 'ruby-ldap'
+</pre>
+
+Bundler will install the gems automatically when you run
+'bundle install'.
+
+You also need to include the ActiveLdap railtie in
+config/application.rb, after the other railties:
+
+<pre>
+require "active_ldap/railtie"
+</pre>
+
+h2. Configuration
+
+You can use a LDAP configuration per environment. They are in
+a file named 'ldap.yml' in the config directory of your
+rails app. This file has a similar function to the
+'database.yml' file that allows you to set your database
+connection configurations per environment. Similarly, the
+ldap.yml file allows configurations to be set for
+development, test, and production environments.
+
+You can generate 'config/ldap.yml' by the follwoing command:
+
+<pre class="command">
+% script/rails generate active_ldap:scaffold
+</pre>
+
+You need to modify 'config/ldap.yml' generated by
+active_ldap:scaffold. For instance, the development entry
+would look something like the following:
+
+<pre>
+!!!plain
+development:
+  host: 127.0.0.1
+  port: 389
+  base: dc=localhost
+  bind_dn: cn=admin,dc=localhost
+  password: secret
+</pre>
+
+When your application starts up,
+ActiveLdap::Base.setup_connection will be called with the
+parameters specified for your current environment.
+
+h2. Model
+
+You can generate a User model that represents entries under
+ou=Users by the following command:
+
+<pre class="command">
+% script/rails generate model User --dn-attribute uid --classes person PosixAccount
+</pre>
+
+It generates the following app/model/user.rb:
+
+<pre>
+class User < ActiveLdap::Base
+  ldap_mapping :dn_attribute => "uid",
+               :prefix => "ou=Users",
+               :classes => ["person", "PosixAccount"]
+end
+</pre>
+
+You can add relationships by modifying app/model/user.rb:
+
+<pre>
+class User < ActiveLdap::Base
+  ldap_mapping :dn_attribute => 'uid',
+               :prefix => "ou=Users",
+               :classes => ['person', 'posixAccount']
+  belongs_to :primary_group,
+             :class_name => "Group",
+             :foreign_key => "gidNumber",
+             :primary_key => "gidNumber"
+  belongs_to :groups,
+             :many => 'memberUid'
+end
+</pre>
+
+You can also generate a Group model by the following command:
+
+<pre class="command">
+% script/rails generate model Group --classes PosixGroup
+</pre>
+
+app/model/group.rb:
+
+<pre>
+class Group < ActiveLdap::Base
+  ldap_mapping :dn_attribute => "cn",
+               :prefix => "ou=Groups",
+               :classes => ["PosixGroup"]
+end
+</pre>
+
+You can add relationships by modifying app/model/group.rb:
+
+<pre>
+class Group < ActiveLdap::Base
+  ldap_mapping :dn_attribute => "cn",
+               :prefix => "ou=Groups",
+               :classes => ["PosixGroup"]
+  has_many :members,
+           :class_name => "User",
+           :wrap => "memberUid"
+  has_many :primary_members,
+           :class_name => "Group",
+           :foreign_key => "gidNumber",
+           :primary_key => "gidNumber"
+end
+</pre>
+
+You can also generate a Ou model by the following command:
+
+<pre class="command">
+% script/rails generate model Ou --prefix '' --classes organizationalUnit
+</pre>
+
+<pre>
+class Ou < ActiveLdap::Base
+  ldap_mapping :dn_attribute => "cn",
+               :prefix => "",
+               :classes => ["organizationalUnit"]
+end
+</pre>