Usage

Logging In

Once you have finished configuring your authentication provider, you are ready to start authenticating users.

Before you get started, make sure you have either created a new authentication guard that uses your new provider, or change the default guard to use your new provider. For now, let's change our default web guard to use our new ldap provider:

// config/auth.php

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

    // ...
],

Now that we have updated our default authentication guard to use our new ldap provider, we will jump into the default LoginController that is included with Laravel. For this example application, we will authenticate our LDAP users with their email address using the LDAP attribute mail.

To have LdapRecord properly locate the user in your directory, we will override the credentials method in this controller:

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

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

As you can see above, we set the mail key which is passed to the LdapRecord authentication provider.

A search query will be executed on your directory for a user that contains the mail attribute equal to the entered email that the user has submitted on your login form. The password key is automatically bypassed and will not be used in the search.

If a user is not found in your directory, or they fail authentication, they will be redirected to the login page normally with the "Invalid credentials" error message.

Using Usernames

In corporate environments, users are often used to signing into their computers with their username. You can certainly keep this flow easy for them - we just need to change a couple things.

First, you will need to change the email column in the database migration that creates your users table to username, as this represents what it will now contain:

Schema::create('users', function (Blueprint $table) {
    // ...

    // Before...
    $table->string('email')->unique(); 

    // After...
    $table->string('username')->unique(); 
});

Make sure you run your migrations using php artisan migrate.

Once we've changed the name of the column, we'll jump into the config/auth.php configuration and modify our LDAP user providers sync_attributes to synchronize this changed column. In this example, we will use the users sAMAccountName as their username which is common in ActiveDirectory environments:

// config/auth.php

'providers' => [
    // ...

    'ldap' => [
        // ...

        'database' => [
            // ...

            'sync_attributes' => [
                'name' => 'cn',
                'username' => 'samaccountname',
            ],
        ],
    ],
],

Now, since we have changed the way our users sign into our application from the default email field, we need to modify our HTML login form to reflect this. Let's jump into our auth/login.blade.php:

<!-- resources/views/auth/login.blade.php -->

<!-- Before... -->
<input id="email" type="email" class="form-control @error('email') is-invalid @enderror" name="email" value="{{ old('email') }}" required autocomplete="email" autofocus>

<!-- After... -->
<input id="username" type="text" class="form-control @error('username') is-invalid @enderror" name="username" value="{{ old('username') }}" required autocomplete="username" autofocus>

After changing the HTML input, we now must modify our LoginController to use this new field. We do this by overriding the username method, and updating our credentials method:

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

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

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

You can now sign into your application using usernames instead of email addresses.

Eloquent Model Binding

If you are using database synchronization, model binding allows you to attach the users LdapRecord model to their Eloquent model so their LDAP data is available on every request automatically.

Enabling this option will perform a single query on your LDAP server for a logged in user per request. This could lead to slightly longer load times depending on your LDAP server and network speed.

To begin, insert the LdapRecord\Laravel\Auth\HasLdapUser trait onto your User model:

namespace App;

use LdapRecord\Laravel\Auth\HasLdapUser;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasLdapUser;

Now, after an LDAP user logs into your application, their LdapRecord model will be available on their model via the ldap property:

// Instance of App\User
$user = Auth::user();

// Instance of App\Ldap\User
$ldap = $user->ldap;

echo $ldap->getFirstAttribute('cn');

Pass-through Authentication / SSO

Pass-through authentication allows your users to be automatically signed in when they access your application on a Windows domain joined computer. This feature is ideal for in-house corporate environments.

However, this feature assumes that you have enabled Windows Authentication in IIS, or have enabled it in some other means with Apache. LdapRecord does not set this up for you. To enable Windows Authentication, visit the IIS configuration guide.

When you have it enabled on your server and a user visits your application from a domain joined computer, the users sAMAccountName becomes available on a PHP server variable ($_SERVER['AUTH_USER']).

LdapRecord provides a middleware that you apply to your stack which retrieves this username from the request, attempts to locate the user in your directory, then logs the user in.

To use the middleware, insert it on your middleware stack inside your app/Http/Kernel.php file:

protected $middlewareGroups = [
    'web' => [
        // ...
        \LdapRecord\Laravel\Middleware\WindowsAuthenticate::class,
    ],
];

The WindowsAuthenticate middleware uses the rules you have configured inside your config/auth.php file. A user may successfully authenticate against your LDAP server when visiting your site, but depending on your rules, may not be imported or logged in.

← Previous Topic

Configuration

Next Topic →

Multi-Domain