Laravel IAM — Directory

Bring your LDAP / Active Directory into Laravel IAM — safely.
Directory login, Just-In-Time provisioning and group → role mapping, hardened against the classic identity-sync pitfalls.

📖 Read the documentation →

Why this package

Most teams already have their users in LDAP or Active Directory. Wiring that into an app usually means one of two bad outcomes: a brittle hand-rolled bind that silently fails open, or a "sync everything" job that happily takes over local accounts, keeps stale privileges forever, and lets a single wrong row in a group-mapping table escalate a user to admin.

laravel-iam-directory is the optional Directory module of Laravel IAM. It authenticates against your directory, provisions users Just-In-Time on first login, and keeps their IAM roles in sync with their directory groups — while closing every one of those pitfalls by design:

• Anti-takeover — an email already owned by a non-directory account is never auto-linked. You get a conflict, not a hijack.
• No privilege persistence — drop a user from an LDAP group and the matching role is revoked on the next sync. Manually-granted roles are never touched.
• Protected roles — list the roles (e.g. iam:super_admin) that can never be granted through group mapping, no matter what the directory says.
• Fail-closed — bad credentials or a connector error resolve to denied, never to a half-provisioned user.

The real LDAP transport (LdapRecord) is optional and isolated: the core works against any DirectoryConnector, so you can test, map and provision without ext-ldap installed.

Features

• DirectoryAuthenticator — the login entry point: authenticate → map groups → provision/sync, all fail-closed.
• GroupMapper — maps a user's directory groups to IAM roles (full_key), accepting both the full DN and the short CN, case-insensitively. Unmapped groups are ignored (default-deny — no implicit roles).
• DirectoryProvisioner — JIT on first login (creates user + membership + grants) and an authoritative, idempotent sync afterwards that adds missing roles and revokes stale directory-sourced ones.
• DirectoryJitPolicy — secure-by-default: require_verified_email, allowed_domains, approval_required, default_roles, group_mapping, and protected_roles.
• DirectoryUser / DirectoryConnector — a normalized identity and a transport seam, so the core is decoupled from LDAP and trivially testable.
• DirectoryOutcome — a typed result: provisioned · linked · conflict · pending · denied.
• Optional Ldap\LdapConnector — the real LDAP/AD transport via LdapRecord, isolated so the package installs and analyses cleanly without ext-ldap.

Use cases

• SSO-less LDAP/AD login. Let enterprise users sign in with their directory credentials, without standing up a full SAML/OIDC IdP.
• Auto-provision on first login. New hire appears in AD → on first login they get an IAM user, membership and the right roles, with no manual onboarding.
• Keep roles in sync with AD groups — safely. Group membership changes flow into IAM roles on every login, with stale roles revoked and protected roles never auto-granted.

Installation

Requirements: PHP 8.3+, Laravel 13, and a running Laravel IAM server (padosoft/laravel-iam-server).

The real LDAP/Active Directory transport is optional and needs the PHP ext-ldap extension:

Without it, the core (group mapping + JIT) still works against any DirectoryConnector you provide — handy for tests and non-LDAP sources.

Publish the config:

Quick start

1. Configure the directory & mapping

config/iam-directory.php:

2. Authenticate a user against the directory

3. The roles stay in sync — automatically

On every login the provisioner re-syncs the user's directory-sourced roles:

• user added to developers in AD → gets app:developer, app:deployer
• user removed from warehouse-admins → warehouse:admin is revoked (manual grants untouched)
• iam:super_admin mapped by a rogue group row → ignored (it's a protected role)

4. Use a custom (non-LDAP) source

Implement DirectoryConnector to provision from any source — no ext-ldap needed:

⚠️ Security model. This module is deliberately strict: it refuses account takeover by email collision, revokes stale directory roles on sync, and never grants protected_roles from the directory. Don't relax these in a custom connector — see docs/provisioning-and-security.md.

Ecosystem

Documentation

📖 Full documentation: doc.laravel-iam-directory.padosoft.com — a 22-page docmd site with semantic search, covering:

• Get started — Quickstart, Installation, Core concepts
• Guides — Directory login, Group → role mapping, JIT provisioning & sync, Custom connector
• Security & theory — Anti-takeover, Authoritative sync, Protected roles, Fail-closed transport
• Architecture — overview, login pipeline, data model, ADR
• Reference — PHP API, config keys, outcomes & reasons

The Markdown sources live in docs-site/docs/; the site is built with docmd and deployed to Cloudflare Pages.

Security

Laravel IAM is fail-closed by design. This module adds directory-specific hardening: anti-takeover (email collision → conflict), stale-privilege revocation on sync, and protected_roles that the directory can never grant. The directory assigns roles; the PDP, not this module, decides allow/deny. If you discover a security issue, email [email protected] rather than opening a public issue.

License

MIT © Padosoft. See LICENSE.