zcgl/vendor/adldap2/adldap2-laravel/docs/upgrading.md

Upgrade Guide

Upgrading from 5.* to 6.*

Estimated Upgrade Time: 1 hour

Minimum Requirements

Adldap2-Laravel now requires a minimum of Laravel 5.5, as all previous versions are now out of their respective support windows.

If you require using an earlier version of Laravel, please use Adldap2-Laravel v5.0.

Configuration

It is recommended to re-publish both of your ldap.php and ldap_auth.php files to ensure you have all of the updated configuration keys.

You can do so by deleting your ldap.php and ldap_auth.php files and then running:

• php artisan vendor:publish --provider=Adldap\Laravel\AdldapServiceProvider
• php artisan vendor:publish --provider=Adldap\Laravel\AdldapAuthServiceProvider

Quick Changes View

Here's a quick overview of the configuration changes made in their respective files:

// ldap.php

// v5.0
// Non-existent

// v6.0
'logging' => env('LDAP_LOGGING', true),

// ldap_auth.php

// v5.0
'usernames' => [

    'ldap' => [
        'discover' => 'userprincipalname',
        'authenticate' => 'distinguishedname',
    ],
    
    'eloquent' => 'email',
    
    'windows' => [
        'discover' => 'samaccountname',
        'key' => 'AUTH_USER',  
    ],

],

// v6.0
'model' => App\User::class,

'identifiers' => [

    'ldap' => [
        'locate_users_by' => 'userprincipalname',
        'bind_users_by' => 'distinguishedname',
    ],

    'database' => [
        'guid_column' => 'objectguid',
        'username_column' => 'email',
    ],

    'windows' => [
        'locate_users_by' => 'samaccountname',
        'server_key' => 'AUTH_USER',
    ],
    
]

Authentication

Object GUID Database Column

When using the DatabaseUserProvider, you must now create a database column to store users objectguid. This allows usernames to change in your directory and synchronize properly in your database. This also allows you to use multiple LDAP directories / domains in your application.

This column is configurable via the guid_column located in the database configuration array:

    'database' => [

        'guid_column' => 'objectguid',

        //

If you're starting from scratch, simply add the objectguid column (or whichever column you've configured) to your users migration file:

Schema::create('users', function (Blueprint $table) {
    $table->increments('id');
    $table->string('objectguid')->unique()->nullable(); // Added here.
    $table->string('name');
    $table->string('email')->unique();
    $table->timestamp('email_verified_at')->nullable();
    $table->string('password');
    $table->rememberToken();
    $table->timestamps();
});

Otherwise if you're upgrading from v5, make another migration and add the column to your users table.

Ex. php artisan make:migration add_objectguid_column

Schema::table('users', function (Blueprint $table) {
    $table->string('objectguid')->unique()->nullable()->after('id');
});

You can learn more about this configuration option here.

Username Database Column

The database.username_column option was renamed from eloquent to more directly indicate what it is used for.

Set this option to your users database username column so users are correctly located from your database.

LDAP Discover and Authenticate

The ldap.discover and ldap.authenticate options have been renamed to ldap.locate_users_by and ldap.bind_user_by respectively.

They were renamed to more directly indicate what they are used for.

Windows Discover and Key

The windows.discover and windows.key options were renamed to windows.locate_users_by and windows.server_key to follow suit with the above change and to directly indicate what it is used for.

LDAP

Logging

The logging option has been added to automatically enable LDAP operation logging that was added in Adldap2 v10.0.

Simply set this to false if you would not like operation logging enabled. Any connections you specify in your connections configuration will be logged.

Upgrading from 4.* to 5.*

Estimated Upgrade Time: 30 minutes

Functionally, you should not need to change the way you use Adldap2-Laravel. There have been no major API changes that will impact your current usage.

However, there have been API changes to the core Adldap2 package. It is heavily recommended to read the release notes to see if you may be impacted.

Requirements

Adldap2-Laravel's PHP requirements has been changed. It now requires a minimum of PHP 7.1.

However, Adldap2's Laravel requirements have not changed. You can still use all versions of Laravel 5.

Configuration

Both Adldap2's configuration files have been renamed to ldap.php and ldap_auth.php for simplicity.

Simply rename adldap.php to ldap.php and adldap_auth.php to ldap_auth.php.

If you'd prefer to re-publish them from scratch, here's a quick guide:

1. Delete your config/adldap.php file
2. Run php artisan vendor:publish --provider="Adldap\Laravel\AdldapServiceProvider"

If you're using the Adldap2 authentication driver, repeat the same steps for its configuration:

1. Delete your config/adldap_auth.php file
2. Run php artisan vendor:publish --provider="Adldap\Laravel\AdldapAuthServiceProvider"

Prefix and Suffix Changes

The configuration options admin_account_prefix and admin_account_suffix have been removed. Simply apply a prefix and suffix to the username of the administrator account in your configuration.

The account_prefix and account_suffix options now only apply to user accounts that are authenticated, not your configured administrator account.

This means you will need to add your suffix or prefix onto your configured administrators username if you require it.

Connection Settings

The configuration option named connection_settings inside each of your configured connections in the adldap.php (now ldap.php) configuration file has been renamed to settings for simplicity.

Authentication Driver

The authentication driver name has been renamed to ldap instead of adldap. This is for the sake of simplicity.

Open your auth.php file and rename your authentication driver to ldap:

'users' => [
    'driver' => 'ldap', // Renamed from 'adldap'
    'model' => App\User::class,
],

Upgrading From 3.* to 4.*

Estimated Upgrade Time: 1 hour

With v4.0, there are some significant changes to the code base.

This new version utilizes the newest v8.0 release of the underlying Adldap2 repository.

Please visit the Adldap2 repository for the release notes and changes.

However for this package you should only have to change your adldap_auth.php configuration.

Authentication Driver

LDAP connection exceptions are now caught when authentication attempts occur.

These exceptions are logged to your configured logging driver so you can view the stack trace and discover issues easier.

Configuration

1. Delete your config/adldap_auth.php
2. Run php artisan vendor:publish --tag="adldap"
3. Reconfigure auth driver in config/adldap_auth.php

Usernames Array

The usernames array has been updated with more options.

You can now configure the attribute you utilize for discovering the LDAP user as well as authenticating.

This will help users who use OpenLDAP and other distributions of directory servers.

Each configuration option is extensively documented in the published file, so please take a moment to review it once published.

This array now also contains the windows_auth_attribute array (shown below).

// v3.0
'usernames' => [

    'ldap' => 'userprincipalname',

    'eloquent' => 'email',
    
],

// v4.0
'usernames' => [

     'ldap' => [
     
        'discover' => 'userprincipalname',
        
        'authenticate' => 'distinguishedname',
        
    ],
    
    'eloquent' => 'email',
    
    'windows' => [
    
        'discover' => 'samaccountname',
        
        'key' => 'AUTH_USER',
        
    ],
    
],

Logging

Logging has been added for authentication requests to your server.

Which events are logged can be configured in your adldap_auth.php file.

Here's an example of the information logged:

[2017-11-14 22:19:45] local.INFO: User 'Steve Bauman' has been successfully found for authentication.  
[2017-11-14 22:19:45] local.INFO: User 'Steve Bauman' is being imported.  
[2017-11-14 22:19:45] local.INFO: User 'Steve Bauman' is being synchronized.  
[2017-11-14 22:19:45] local.INFO: User 'Steve Bauman' has been successfully synchronized.  
[2017-11-14 22:19:45] local.INFO: User 'Steve Bauman' is authenticating with username: 'sbauman@company.org'  
[2017-11-14 22:19:45] local.INFO: User 'Steve Bauman' has successfully passed LDAP authentication.  
[2017-11-14 22:19:46] local.INFO: User 'Steve Bauman' has been successfully logged in.  

Resolver

The resolver configuration option has now been removed.

It has been modified to utilize Laravel's Facades so you can now swap the implementation at runtime if you wish.

The complete namespace for this facade is below:

Adldap\Laravel\Facades\Resolver

Usage:

use Adldap\Laravel\Facades\Resolver;

Resolver::swap(new MyResolver());

Importer

The importer configuration option has now been removed.

The importer command is bound to Laravel's IoC and can be swapped out with your own implementation if you wish.

NoDatabaseUserProvider

The NoDatabaseUserProvider will now locate users by their ObjectGUID instead of their ObjectSID.