Download the PHP package clarkewing/handoff without Composer

Handoff

Handoff is a Laravel package that enables seamless, secure cross-application authentication via temporary signed URLs. It’s ideal for projects maintaining both a legacy and a modern Laravel app, and ensures users can be automatically logged in across both systems without friction.

🚀 Features

• 🔐 Secure authentication handoff via signed URLs
• 🔁 Bi-directional route mapping between apps
• ⏱️ Expirable links with configurable TTL
• ⚙️ Fully customizable user model & identifier
• 🌍 Shared, environment-agnostic logic — install on both apps

🧩 Requirements

To use Handoff, the package must be installed in both Laravel applications you wish to link and their User models must be kept in sync.

Handoff is compatible with applications using Laravel 8 and above, and requires PHP 8.0 or above.

📦 Installation

Handoff must be installed in both your origin app and the target app.

In your origin app’s .env file, register the target host:

⚙️ Configuration

Optionally, you can publish the config file using the following command.

Note: This is required if you want to use route mapping (see the Usage section).

These are the contents of the published config file:

🔧 Usage

Target app

In the target app, Handoff automatically registers a /handoff endpoint via its service provider. This endpoint validates the signed URL, logs the user in, and redirects them to the intended destination.

Origin app

From the origin app, Handoff provides three ways of handing off a request to the target application:

1. Manually generating a signed Handoff URL
2. Automatically redirecting users via the handoff middleware and providing a target path
3. Automatically redirecting users via the handoff middleware while using route mapping

Manually generating a signed Handoff URL

Handoff supplies a GenerateHandoffUrl action class which can be used to manually create a Handoff URL.

Note: Either toPath or fromRoute must be provided, not both.

Automatically redirecting users via the handoff middleware and providing a target path

To simplify redirecting users, Handoff registers its handoff middleware. It accepts a target path to which users will be redirected.

Automatically redirecting users via the handoff middleware while using route mapping

For cases where you’d prefer to centrally manage your handoff origin routes and target paths, Handoff provides the possibility to use route to path mapping.

1. Apply the handoff middleware to origin routes

You have a few options for this. See the Laravel documentation on Registering Middleware.

2. Setup route mapping in the config

After publishing Handoff’s config file, you can set up route mapping:

🔐 Security

This package uses Laravel’s temporarySignedRoute() mechanism. URLs are cryptographically signed and valid only for a limited time. You can customize the TTL or add rate limiting via the included service provider.

🤝 Contributing

Issues and PRs welcome! Please see our Contribution guidelines if contributing tests or features.

📜 License

Released under the MIT License.