Sentry Ldap Laravel Package

Getting Started

1. Install via Composer. This package predates Laravel package auto-discovery, so add it explicitly:

   composer require anndro/sentry_ldap
   

   Because it is a fork of cartalyst/sentry, do not also require cartalyst/sentry in the same project — the namespaces collide. If you pull it into a Laravel app, register the service provider and alias manually in config/app.php:

   'providers' => [
       'Anndro\SentryLdap\SentryLdapServiceProvider',
   ],
   'aliases' => [
       'Sentry' => 'Anndro\SentryLdap\Facades\SentryLdap',
   ],
   

2. Publish and run the migrations. Sentry persists users, groups, permissions, and throttle records to your SQL database. Publish its migrations (php artisan vendor:publish) so the users, groups, users_groups, permissions, users_permissions, group_permissions, and throttle tables exist. You must run these before any authentication call.

3. Configure the connection. Publish/merge the package config and set your LDAP server details (host, port, base DN, account suffix, filter, and the attribute you authenticate on — typically uid or samAccountName), plus your DB connection for persistence.

4. First use case — authenticate against LDAP, persist locally. The canonical flow is: take credentials from your login form, call Sentry::authenticate($credentials, $remember). Sentry binds to LDAP to verify the password, then creates or updates a matching local user row so you get Sentry's groups, permissions, and throttling on top of directory auth.

5. Where to look first. Open the package's SentryLdapServiceProvider and the LDAP driver/hasher it registers — that's where password verification is delegated to LDAP. Read the config to understand how the LDAP username maps to the Sentry users.login (or custom column) before writing any controllers.

Implementation Patterns

• Keep the Sentry facade contract. Because this is a Sentry fork, the day-to-day API is Sentry::authenticate(), Sentry::login(), Sentry::check(), Sentry::getUser(), Sentry::logout(). You can build thin controllers/services on top without learning a new API if you already know Sentry.

• Custom user model. Extend the package's user model and register it in config so you can add app-specific columns and accessors. Sentry's UserInterface/GroupInterface must be implemented if you swap the model entirely. This is the cleanest extension point for adding profile fields.

• LDAP-first, DB-second mapping. A robust pattern is a "sync on login" service: bind to LDAP → read attributes (mail, displayName, memberOf) → Sentry::findUserByLogin() → create or update() the local user → assign Sentry groups based on LDAP memberOf. Keep that logic in one injectable service so it can be unit tested with a mocked LDAP connection.

• Group/permission synchronization. Use Sentry groups as the authorization layer even though LDAP is the identity source. On every login, reconcile directory groups into Sentry groups (Sentry::findGroupByName() plus $user->addGroup() / removeGroup()), so authorization stays consistent with the directory.

• Session and persistence toggles. Control behavior via Sentry::authenticate($creds, $remember) and config (session, persistence, remember_me). For a stateless API, use Sentry::loginAndRemember()-style flows carefully — Sentry is fundamentally session-based, so guard your API routes with your own token layer.

• Login throttling. Enable the throttle driver in config so repeated failed binds are rate-limited; wrap authenticate() in try/catch for LoginRequiredException and UserNotFoundException and translate them into a single generic login error (don't leak whether the LDAP account exists).

• Registration flow. Sentry::register($attributes, $activate) creates the local user but does not create the LDAP account — decide explicitly whether registration is LDAP-provisioned, admin-provisioned, or just a local mirror row with an LDAP link on first bind. Document that boundary for whoever maintains it.

• Testing. Mock the LDAP bind layer in integration tests (or run against a test directory container) and assert on the Sentry user/group state afterward. Never point tests at production LDAP.

Gotchas and Tips

• This is a 2015 Sentry fork — treat it as legacy. Sentry was superseded by Cartalyst Sentinel, and this fork has had no release since mid-2015 with zero dependents. There is no PHP 7/8 compatibility work, no auto-discovery, and no upstream security fixes. For a new project, prefer modern options (e.g., a maintained LDAP provider like Adldap2/ldaprecord plus a current auth package). Use this only to maintain an existing Sentry-based app.

• Namespace collisions. Installing alongside cartalyst/sentry or any other package that provides a Sentry alias will break silently or fatally. Audit composer.lock and the aliases array before assuming it works.

• LDAP bind quirks. The authentication filter and username attribute are the usual culprits for "wrong password" errors that are actually config problems. Test the raw bind first (e.g., ldapsearch/ldapwhoami) with the same DN format the config builds; if the raw bind fails, Sentry will too. Watch for sAMAccountName vs uid (AD vs OpenLDAP), and for base DN vs user DN mismatches.

• Passwords are never stored hashing-side. The LDAP driver replaces password checking entirely, so local password hashes are irrelevant (and possibly stale) for LDAP users. Any password-reset/reset-link flows you inherited from Sentry are dead weight for those accounts — disable or redirect them.

• Migrations must run first. A very common first-run failure is a Table not found or SQL error from calling Sentry::authenticate() before publishing/running the Sentry migrations. If you see database errors during login, check the migration state before debugging LDAP.

• Config precedence and caching. When changing LDAP config, clear Laravel's config cache (php artisan config:clear) — otherwise you will edit the config file and keep hitting the old server.

• Debugging strategy. Isolate three layers in order: (1) raw LDAP bind works, (2) the package's LDAP driver returns a user object, (3) Sentry persists/finds the local row. Log at each boundary; wrapping authenticate() in a try/catch and dumping the exception class tells you which layer failed (LoginRequiredException = bad credentials; DB errors = persistence; LDAP extension errors = connectivity/extension missing).

• Extension points to rely on. Custom user/group models via config, a replacement hasher, and (in Laravel) the service provider bindings for the Sentry instance. These are safer than forking the package — fork only if you need PHP 8 fixes, and pin your fork's version.

• php-ldap extension required. It is easy to forget when building a container/CI image; the package will throw a class/extension-not-found error that looks like a configuration problem. Add ext-ldap explicitly to composer.json requirements of your app.