<!-- -*- markdown -*- -->

# bhLDAPAuthPlugin #

`bhLDAPAuthPlugin` allows you to use users and groups from an LDAP
directory (Microsoft Active Directory® and possibly others) for
your symfony app's authentication and authorization.

This version supports Symfony 1.4 with Propel 1.6 (sfPropel15Plugin).

## Revision ##

$Id: README 32768 2011-07-14 00:15:50Z Nathan.Vonnahme $

$HeadURL: http://svn.symfony-project.com/plugins/bhLDAPAuthPlugin/branches/1.4_Propel/README $

## What it does ##

`bhLDAPAuthPlugin` does:

   * give your app a web login form similar to sfGuard's, with LDAP password authentication
   * let you authorize parts of your app to users based on their membership in LDAP groups
   * work with Apache on Windows ([XAMPP](http://www.apachefriends.org) rocks; you will need the Devel package) or Linux (probably also other Unix family OSes including Mac OS X).
   * work with Microsoft Active Directory® and possibly other LDAP servers.

It does *NOT*: 

   * provide single sign on/seamless authentication/NTLM/GSSAPI.  For that, you can try [some of these alternatives](http://adldap.sourceforge.net/wiki/doku.php?id=seamless_authentication).  I would try to [run symfony on IIS](http://www.symfony-project.org/more-with-symfony/1_4/en/11-Windows-and-Symfony), or try [Likewise](http://www.likewise.com/).
   * necessarily keep your app from transmitting AD passwords over the network in plain text (use HTTPS for the login; instructions below!)
   * suck as much as having Yet Another user/group database to maintain

## Requirements ##

  * [sfGuardPlugin](http://www.symfony-project.org/plugins/sfGuardPlugin).  Why reinvent the wheel?
  * Your PHP must have OpenLDAP support enabled
  * Microsoft Active Directory® (again, it might work with other LDAP servers)
  * `sfSslRequirementPlugin` is a good idea but not strictly required (see "enable SSL" below).

## Installation ##

*NOTE*: Make sure your PHP includes OpenSSL and OpenLDAP support (see `phpinfo()`) (note, for XAMPP, [this blog post](http://www.rawiriblundell.com/?p=224) was instrumental.)

### Using symfony plugin install

For production use, you can install the plugins the standard way:

Install the `sfGuardPlugin`

    ./symfony plugin:install sfGuardPlugin

Install the `bhLDAPAuthPlugin`

    ./symfony plugin:install bhLDAPAuthPlugin

### Or, stay up-to-date with `svn:externals`

For development (potentially for production too, depending on your
circumstances) I recommend using svn:externals on your plugins
directory to stay in sync with the latest developments.  Run this
command to edit the `svn:externals` property on your plugin directory

    svn propedit svn:externals ./plugins

And here are the correct URLs for downloading the latest from each
plugin's symfony 1.4 (or compatible) branch:

    $ svn propget svn:externals plugins/
    bhLDAPAuthPlugin/         http://svn.symfony-project.com/plugins/bhLDAPAuthPlugin/branches/1.4/
    sfPropel15Plugin/        http://svn.symfony-project.com/plugins/sfPropel15Plugin/branches/1.6
    sfGuardPlugin/    http://svn.symfony-project.com/plugins/sfGuardPlugin/branches/1.3/
    sfSslRequirementPlugin/ http://svn.symfony-project.com/plugins/sfSslRequirementPlugin/branches/1.2/


## Configuration


### 1. Configure LDAPAuth.yml

Edit the domain values in your project's `config/LDAPAuth.yml` (you
can start by copying `plugins/bhLDAPAuthPlugin/config/LDAPAuth.yml` to
`config/LDAPAuth.yml`, as an example)

<pre>
# base for all users and groups
account_suffix      :  "@mydomain"     
base_dn             :  "DC=mydomain,DC=mycompany,DC=com"

# An array of domain controllers. Specify multiple controllers if you 
# would like the class to balance the LDAP queries amongst multiple servers
domain_controllers:
  - 10.41.16.2
  - 10.41.16.3
</pre>


### 2. Activate the plugins

Turn on the plugins in `config/ProjectConfiguration.class.php`
  
        [php]
        class ProjectConfiguration extends sfProjectConfiguration
        {
          public function setup()
          {
            $this->enablePlugins(array(
              'sfPropel15Plugin', 
              'sfGuardPlugin',
              'sfSslRequirementPlugin',
	      'bhLDAPAuthPlugin',
              '...'
            ));
          }
        }


### 3. Rebuild your model.  

This adds the Propel object models for tables that `sfGuardPlugin`
needs to your database, even though we won't be using most of them.

    ./symfony  propel:build --model --sql

Update you database tables by starting from scratch (it will delete all
the existing tables, then re-create them):
  
    ./symfony propel:insert-sql

*or*, you can create the new tables manually using the generated SQL
statements that have been appended to `data/sql/schema.sql`.

(Don't load the default sfGuardPlugin fixtures)

### 4.  Clear your cache

    symfony cc


### 5. Enable "Remember Me" (optional)

Optionally enable the "Remember Me" filter above the security filter in `apps/frontend/config/filters.yml` 

    remember_me:
      class: sfGuardRememberMeFilter

    security: ~


### 6. Edit your application's config files 

#### a. settings.yml

Enable the `sfGuardAuth` and `bhLDAPAuth` modules under `.settings` in
`apps/frontend/config/settings.yml`

    all:
      .settings:
        enabled_modules: [default, ..., sfGuardAuth, bhLDAPAuth]

***NOTE:*** at this time, it's also necessary to turn off CSRF protection here.  I think it is because we mix the bhLDAPAuth module's forms with the forms from sfGuardAuth.  Any help or patches are appreciated!

        csrf_secret:            false


Change the default login and secure modules under `all:``.actions` in
`apps/frontend/config/settings.yml`

    all:
      .actions:
	login_module:           bhLDAPAuth
	login_action:           signin

	secure_module:          sfGuardAuth
	secure_action:          secure

#### b. app.yml

Tell `sfGuard` to use the password checker in `bhLDAPAuth` in
`apps/frontend/config/app.yml`, and set `routes:register` false so the bhLDAP routes will override.
  
    all:
      sf_guard_plugin:
	check_password_callable:   [bhLDAP, checkPassword]
	routes_register: false

#### c. `myUser` class

Change the parent class to bhLDAPAuthSecurityUser in
`apps/frontend/lib/myUser.class.php`

    [php]
    class myUser extends bhLDAPAuthSecurityUser
    {
    }


### 7. Apply security to some modules or the whole app
 
Secure some modules or your entire application in
`apps/frontend/config/security.yml`.  Read more about security in
[chapter 6 of the symfony
book](http://www.symfony-project.org/book/1_2/06-Inside-the-Controller-Layer#chapter_06_action_security).

To require users to log in to access *any* module of the application,

    # don't secure login or error pages or you'll make a loop.
    login:
      is_secure: off
      require_ssl: true

    error404:
      is_secure: off
      require_ssl: false

    disabled:
      is_secure: off
      require_ssl: false

    # require authnz for everything else
    default:
      is_secure: on

*Or*, to secure the `article` module but not the entire app, edit
 `apps/frontend/modules/article/config/security.yml`

    default:
      is_secure: on


At this point your application (or certain modules) is restricted to
users who can supply valid AD credentials.


#### 8. enable SSL protection of login form

You don't want your AD credentials flying around the network in clear text, right?  

a. Install the [sfSslRequirementPlugin](http://www.symfony-project.org/plugins/sfSslRequirementPlugin) into your project's plugin dir (or use the `svn:externals` method, above).  
  
    ./symfony plugin:install sfSslRequirementPlugin

b. Complete the installation (editing `filters.yml` and clearing
cache) according to [sfSslRequirementPlugin's README](http://www.symfony-project.org/plugins/sfSslRequirementPlugin/2_0_0?tab=plugin_readme)

c. The bhLDAPAuthPlugin `security.yml` file already turns SSL on for
the signin and login action.

d. You're done. Now, if you try to access a secure page, you will be
redirected to the login page.



## Authorization: Granting different permissions to different LDAP groups 

Imagine your application is a blog, with articles and comments, and
you want the following access scheme:

* users in the `HumanResources` Active Directory group can post and edit articles
* users in the `IntranetUsers` group can add comments or update their own comments

Now that you have bhLDAPAuth configured, it's easy!

a. Edit the `groupMappings` section of `config/LDAPAuth.yml`:

<pre>
    groupMappings:
      #  These settings map symfony credentials to AD groups.
      #  The credentials are applied to actions based on your app's config/security.yml file
      #  See chapter 6 (Inside the Controller Layer) of the book for more about credentials
      reader :
        - IntranetUsers
        - HumanResources
      editor  :
        - HumanResources
</pre>

b. Edit the `security.yml` file in each of your modules' `config`
directory to limit the actions to users with the appropriate
credentials.

For articles, edit
`apps/myapp/modules/article/config/security.yml`, adding a section
for each of your `article` module's actions:

    view:
      credentials: reader

    list:
      credentials: reader

    create:
      credentials: editor

    edit:
      credentials: editor

    update:
      credentials: editor

For comments, edit `apps/myapp/modules/comment/config/security.yml`:

    view:
      credentials: reader

    list:
      credentials: reader

    create:
      credentials: reader

    edit:
      credentials: reader

    update:
      credentials: reader


## Thanks ##

This is all on the shoulders of giants.  Besides
[symfony](http://symfony-project.com) and
[sfGuardPlugin](http://www.symfony-project.com/plugins/sfGuardPlugin),
it includes code from 
[the `adLDAP` PHP library](http://adldap.sourceforge.net/).

## Authors ##

* Nathan Vonnahme (nathan dot vonnahme at banner health dot com)
* Todd McNeill ( todd dot mcneill at pmi group dot com )
* Sam Wilson ( swilson at kahn code labs dot net )

## TODO ##

* test and document non-AD LDAP servers

## Changelog ##

### 6.0
* nathan: release for symfony 1.4 with Propel 1.6 (sfPropel15Plugin)
* CSRF fix from Gabriele Franzini

### 5.0.2
* CSRF fix from Gabriele Franzini


### 5.0.1

* Nathan: rewrote debugDump which was causing trouble (PHP crashes) in some cases
* Nathan: fixed bug preventing the first login for each user

### 5.0

* nathan: release for symfony 1.4 with Doctrine.

### 1.0 - 4.0

* nathan: out of "alpha", releases for symfony 1.0, 1.1, 1.2 and 1.2 with Doctrine.

### 0.2, 0.3, 0.4, 0.5 ###

* nathan: doc tweaks (grrr)

### 0.1 ###

* nathan: initial release