More documentation.

Author: stevebauman

docs/auth/binding.md

@@ -0,0 +1,39 @@
+# Binding the Adldap2 User Model to the Laravel User Model
+
+> **Note**: Before we begin, enabling this option will perform a single query on your AD server for a logged in user
+**per request**. Eloquent already does this for authentication, however this could lead to slightly longer load times
+(depending on your AD server and network speed of course).
+
+To begin, insert the `Adldap\Laravel\Traits\HasLdapUser` trait onto your `User` model:
+
+```php
+namespace App;
+
+use Adldap\Laravel\Traits\HasLdapUser;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Illuminate\Foundation\Auth\User as Authenticatable;
+
+class User extends Authenticatable
+{
+    use SoftDeletes, HasLdapUser;
+```
+
+Now, after you've authenticated a user via the `adldap` driver, their LDAP model is available on their `User` model:
+
+```php    
+if (Auth::attempt($credentials)) {
+    $user = Auth::user();
+    
+    var_dump($user); // Returns instance of App\User;
+    
+    var_dump($user->ldap); // Returns instance of Adldap\Models\User;
+   
+    // Examples:
+    
+    $user->ldap->getGroups();
+    
+    $user->ldap->getCommonName();
+    
+    $user->ldap->getConvertedSid();
+}
+```

docs/auth/fallback.md

@@ -0,0 +1,32 @@
+# Login Fallback
+
+The login fallback option allows you to login as a local database user using the Eloquent authentication driver if 
+active directory authentication fails. This option would be handy in environments where:
+ 
+- You may have some active directory users and other users registering through the website itself (user does not exist in your AD).
+- Local development where your AD server may be unavailable
+
+To enable it, simply set the option to true in your `config/adldap_auth.php` configuration file:
+
+```php
+'login_fallback' => false, // Set to true.
+```
+
+## Developing Locally without an AD connection
+
+You can continue to develop and login to your application without a connection to your AD server in the following scenario:
+
+* You have `auto_connect` set to `false` in your `adldap.php` configuration
+ > This is necessary so we don't automatically try and bind to your AD server when your application boots.
+
+* You have `login_fallback` set to `true` in your `adldap_auth.php` configuration
+ > This is necessary so we fallback to the standard `eloquent` auth driver.
+
+* You have `password_sync` set to `true` in your `adldap_auth.php` configuration
+ > This is necessary so we can login to the account with the last password that was used when an AD connection was present.
+
+* You have logged into the synchronized LDAP account previously
+ > This is necessary so the account actually exists in your local app's database.
+
+If you have this configuration, you will have no issues developing an
+application without a persistent connection to your LDAP server.

docs/auth/multiple-connections.md

@@ -0,0 +1,50 @@
+# Using Multiple LDAP Connections
+
+To swap connections on the fly, set your configurations default connection and try re-authenticating the user:
+
+```php
+$auth = false;
+
+if (Auth::attempt($credentials)) {
+    $auth = true; // Logged in successfully
+} else {
+    // Login failed, swap and try other connection.
+    Config::set('adldap_auth.connection', 'other-connection');
+    
+    if (Auth::attempt($credentials)) {
+        $auth = true; // Passed logging in with other connection.
+    }
+}
+
+if ($auth === true) {
+    return redirect()
+        ->to('dashboard')
+        ->with(['message' => 'Successfully logged in!']);
+}
+
+return redirect()
+        ->to('login')
+        ->with(['message' => 'Your credentials are incorrect.']);
+```
+
+Or, if you'd like to all of your LDAP connections:
+
+```php
+$connections = config('adldap.connections');
+
+foreach ($connections as $connection => $config) {
+
+    // Set the LDAP connection to authenticate with.
+    config(['adldap_auth.connection' => $connection]);
+
+    if (Auth::attempt($credentials)) {
+        return redirect()
+            ->to('dashboard')
+            ->with(['message' => 'Successfully logged in!']);
+    }
+}
+
+return redirect()
+        ->to('login')
+        ->with(['message' => 'Your credentials are incorrect.']);
+```

docs/auth/syncing.md

@@ -0,0 +1,78 @@
+# Syncing Attributes
+
+Inside your `config/adldap_auth.php` file there is a configuration option named `sync_attributes`. This
+is an array of attributes where the key is the eloquent `User` model attribute, and the
+value is the active directory users attribute.
+
+By default, the `User` models `email` and `name` attributes are synchronized to
+the LDAP users `userprincipalname` and `cn` attributes.
+
+This means, upon login, the users `email` and `name` attribute on Laravel `User` Model will be set to the
+LDAP users `userprincipalname` and common name (`cn`) attribute, **then saved**.
+
+Feel free to add more attributes here, however be sure that your `users` database table
+contains the key you've entered, otherwise you will receive a SQL exception.
+
+## Sync Attribute Handlers
+
+If you're looking to synchronize an attribute from an Adldap2 model that contains an array or an
+object, or sync attributes yourself, you can use an attribute handler class
+to sync your model attributes manually. For example:
+
+> **Note**: The class must contain a `handle()` method. Otherwise you will receive an exception.
+
+> **Tip**: Attribute handlers are constructed using the `app()` helper. This means you can type-hint any application
+> dependencies you may need in the handlers constructor.
+
+```php
+'sync_attributes' => [
+    
+    App\Handlers\LdapAttributeHandler::class,
+
+],
+```
+
+The `LdapAttributeHandler`:
+
+```php
+namespace App\Handlers;
+
+use App\User as EloquentUser;
+use Adldap\Models\User as LdapUser;
+
+class LdapAttributeHandler
+{
+    /**
+     * Synchronizes ldap attributes to the specified model.
+     *
+     * @param LdapUser     $ldapUser
+     * @param EloquentUser $eloquentUser
+     *
+     * @return void
+     */
+    public function handle(LdapUser $ldapUser, EloquentUser $eloquentUser)
+    {
+        $eloquentUser->name = $ldapUser->getCommonName();
+    }
+}
+```
+
+## Password Synchronization
+
+The password sync option allows you to automatically synchronize
+users AD passwords to your local database. These passwords are
+hashed natively by laravel.
+
+Enabling this option would also allow users to login to their
+accounts using the password last used when an AD connection
+was present.
+
+If this option is disabled, the local user account is applied
+a random 16 character hashed password, and will lose access
+to this account upon loss of AD connectivity.
+
+This feature is enabled by default.
+
+```php
+'password_sync' => env('ADLDAP_PASSWORD_SYNC', true),
+```