Authentication Quickstart

Before you get started with the LDAP authentication driver please complete the LdapRecord-Laravel quickstart guide to install LdapRecord and configure your LDAP connection.

Introduction

Before you begin, this guide assumes you have published Laravel's default authentication scaffolding.

If you have not yet done so, please follow Laravel's documented guide to get started, and head back here once done.

Debugging

Inside of your config/ldap.php file, ensure you have logging enabled during the setup of authentication.

Doing this will help you immensely in debugging connectivity and authentication issues.

If you encounter issues along the way, be sure to open your storage/logs directory and see what may be occurring.

Plain LDAP Authentication

Step 1: Configure the Authentication Driver

Inside of your config/auth.php file, we must add a new provider in the providers array.

In this example, we will create a provider named ldap:

// config/auth.php

'providers' => [
    // ...

    'ldap' => [
        'driver' => 'ldap',
        'model' => LdapRecord\Models\ActiveDirectory\User::class,
    ],

Once you have setup your ldap provider, you must update the provider value in the web guard:

// config/auth.php

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'ldap', // Changed to 'ldap'
    ],

    // ...

Step 2: Setting up your LoginController

Now we must change our LoginController to allow LdapRecord to properly locate users who are attempting to sign into our application.

We do this by changing the credentials method and returns an array that contains the users username and password. The username in this example will be the LDAP users mail attribute:

class LoginController extends Controller
{
    // ...

    protected function credentials(Request $request)
    {
        return [
            'mail' => $request->get('email'),
            'password' => $request->get('password'),
        ];
    }
}

Step 3: Modifying The Layout Blade View

When we use plain LDAP authentication, an instance of the LdapRecord model you have configured for authentication will be returned when calling the Auth::user() method. This means that our currently published blade views will throw an exception due to using Auth::user()->name inside of the view file views/layouts/app.blade.php.

You must change the syntax to the following:

<!-- resources/views/layouts/app.blade.php -->

<!-- From... -->
<a id="navbarDropdown" class="nav-link dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" v-pre>
    {{ Auth::user()->name }} <span class="caret"></span>
</a>

<!-- To... -->
<a id="navbarDropdown" class="nav-link dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false" v-pre>
    {{ Auth::user()->getFirstAttribute('cn') }} <span class="caret"></span>
</a>

Your application is now ready to authenticate LDAP users.

Synchronized Database Authentication

Step 1: Publish the Migration

LdapRecord requires you to have two additional user database columns.

Column Reason
guid This is for storing your LDAP users objectguid. It is needed for locating and synchronizing your LDAP user to the database.
domain This is for storing your LDAP users connection name. It is needed for storing your configured LDAP connection name of the user.

Go ahead and publish the migration using the below command:

php artisan vendor:publish --provider="LdapRecord\Laravel\LdapAuthServiceProvider"

Then, run the migrations with the artisan migrate command:

php artisan migrate

Step 2: Configure the Authentication Driver

Inside of your config/auth.php file, we must add a new provider in the providers array.

In this example, we will create a provider named ldap:

// config/auth.php

'providers' => [
    // ...

    'ldap' => [
        'driver' => 'ldap',
        'model' => LdapRecord\Models\ActiveDirectory\User::class,
        'database' => [
            'model' => App\User::class,
            'sync_passwords' => false,
            'sync_attributes' => [
                'name' => 'cn',
                'email' => 'mail',
            ],
        ],
    ],
],

If you are using OpenLDAP, you must switch the providers model option to:

LdapRecord\Models\OpenLDAP\User::class

If you are using a different LDAP type, you will need to define your own LDAP model and insert it there. This model is used for locating the authenticating user in your LDAP directory.

Once you have setup your ldap provider, you must update the provider value in the web guard:

// config/auth.php

'guards' => [
    'web' => [
        'driver' => 'session',
        'provider' => 'ldap', // Changed to 'ldap'
    ],

    // ...

Step 3: Add the trait and interface to your user model

Now, we must add the following trait and interface to our User Eloquent model:

Type Name
Interface LdapRecord\Laravel\Auth\LdapAuthenticatable
Trait LdapRecord\Laravel\Auth\AuthenticatesWithLdap
// app/User.php

// ...
use LdapRecord\Laravel\Auth\AuthenticatesWithLdap;
use LdapRecord\Laravel\Auth\LdapAuthenticatable;

class User extends Authenticatable implements LdapAuthenticatable
{
    use Notifiable, AuthenticatesWithLdap;

    // ...
}

These are required so LdapRecord can set and retrieve your users domain and guid database columns.

If you would like to override the database column names that are used, you can override the following methods:

Methods
User::getLdapDomainColumn()
User::getLdapGuidColumn()

Step 4: Setting up your LoginController:

For LdapRecord to properly locate users that attempt to login to your application, you must override the credentials method in your Auth\LoginController.php file.

Then, you must set an array key of the LDAP attribute that will be used for looking up the user in your LDAP directory.

In the example below, we will lookup LDAP users by their mail attribute:

// app/Http/Controllers/Auth/LoginController.php

// ...
class LoginController extends Controller
{
    // ...

    protected function credentials(Request $request)
    {
        return [
            'mail' => $request->get('email'),
            'password' => $request->get('password'),
        ];
    }
}

Your application is now ready to authenticate LDAP users.

← Previous Topic

Usage

Next Topic →

Overview