zcgl/vendor/adldap2/adldap2-laravel/docs/auth/introduction.md

Introduction

The Adldap2 Laravel auth driver allows you to seamlessly authenticate LDAP users into your Laravel application.

There are two primary ways of authenticating LDAP users:

• Authenticate and synchronize LDAP users into your local applications database:

  This allows you to attach data to users as you would in a traditional application.

  Calling Auth::user() returns your configured Eloquent model (ex. App\User) of the LDAP user.

• Authenticate without keeping a database record for users

  This allows you to have temporary users.

  Calling Auth::user() returns the actual LDAP users model (ex. Adldap\Models\User).

We'll get into each of these methods and how to implement them, but first, lets go through the installation guide.

Quick Start - From Scratch

Here is a step by step guide for configuring Adldap2-Laravel (and its auth driver) with a fresh new laravel project. This guide assumes you have knowledge working with:

• Laravel
• The LDAP Protocol
• Your LDAP distro (ActiveDirectory, OpenLDAP, FreeIPA)
• Command line tools (such as Composer and Laravel's Artisan).

This guide was created with the help of @st-claude and other awesome contributors.

1. Create a new laravel project by running the command:
   • laravel new my-ldap-app
     

Or (if you don't have the Laravel Installer)

• composer create-project --prefer-dist laravel/laravel my-app.

1. Run the following command to install Adldap2-Laravel:

   • composer require adldap2/adldap2-laravel

2. Create a new database in your desired database interface (such as PhpMyAdmin, MySQL Workbench, command line etc.)

3. Enter your database details and credentials inside the .env file located in your project root directory (if there is not one there, rename the .env.example to .env).

4. If you're using username's to login users instead of their emails, you will need to change the default email column in database/migrations/2014_10_12_000000_create_users_table.php.

   // database/migrations/2014_10_12_000000_create_users_table.php
          
   Schema::create('users', function (Blueprint $table) {
       $table->increments('id');
       $table->string('name');
             
       // From:
       $table->string('email')->unique();
             
       // To:
       $table->string('username')->unique();
             
       $table->string('password');
       $table->rememberToken();
       $table->timestamps();
   });
   

5. Now run php artisan migrate.

6. Insert the following service providers in your config/app.php file (in the providers array):

   Note: This step is only required for Laravel 5.0 - 5.4. They are registered automatically in Laravel 5.5.

   Adldap\Laravel\AdldapServiceProvider::class,
   Adldap\Laravel\AdldapAuthServiceProvider::class,
   

7. Now, insert the facade into your config/app.php file (in the aliases array):

   'Adldap' => Adldap\Laravel\Facades\Adldap::class,
   

Note: Insertion of this alias in your app.php file isn't necessary unless you're planning on utilizing it.

1. Now run php artisan vendor:publish in your root project directory to publish Adldap2's configuration files.

   • Two files will be published inside your config folder, ldap.php and ldap_auth.php.

2. Modify the config/ldap.php and config/ldap_auth.php files for your LDAP server configuration.

3. Run the command php artisan make:auth to scaffold login controllers and routes.

4. If you require logging in by another attribute, such as a username instead of email follow the process below for your Laravel version. Otherwise ignore this step.

Laravel <= 5.2

Inside the generated app/Http/Controllers/Auth/AuthController.php, you'll need to add the protected $username property if you're logging in users by username.

  class AuthController extends Controller
  {
      protected $username = 'username';

Laravel > 5.3

Inside the generated app/Http/Controllers/Auth/LoginController.php, you'll need to add the public method username():

  public function username()
  {
      return 'username';
  }

1. Now insert a new auth driver inside your config/auth.php file:

   'providers' => [
     'users' => [
         'driver' => 'ldap', // Was 'eloquent'.
         'model'  => App\User::class,
     ],
   ],
   

2. Inside your resources/views/auth/login.blade.php file, if you're requiring the user logging in by username, you'll need to modify the HTML input to username instead of email. Ignore this step otherwise.

   From:

   <input type="email" class="form-control" name="email" value="{{ old('email') }}">
   

   To:

   <input type="text" class="form-control" name="username" value="{{ old('username') }}">
   

3. You should now be able to login to your Laravel application using LDAP authentication!

   If you check out your database in your users table, you'll see that your LDAP account was synchronized to a local user account.

   This means that you can attach data regularly to this user as you would with standard Laravel authentication.

   If you're having issues, and you're unable to authenticate LDAP users, please check your configuration settings inside the ldap.php and ldap_auth.php files as these directly impact your applications ability to authenticate.

4. Congratulations, you're awesome.