Waterhole 0.4

Waterhole 0.4 is here with new integrations: single sign-on with external authentication providers, and integration into existing Laravel apps.

Highlights

The focus of the 0.4 release is authentication and Laravel integration, making it possible to use Waterhole with your existing user base. There are also a number of other changes and bug fixes which are detailed in the Release Notes.

Single Sign-On

If you have an external site with an existing user base and authentication system that you would like to use, Waterhole now includes a special authentication provider to support this flow.

The updated Authentication docs describe how to set this up, including making the necessary configuration changes to Waterhole and configuring your external site to respond.

If your website uses PHP, you can use the new waterhole/sso package to handle SSO requests for you, making it as easy as this:

use Waterhole\Sso\PendingUser;
use Waterhole\Sso\WaterholeSso;

Route::middleware('auth', 'verified')->get('sso', function () {
    $sso = new WaterholeSso('sso_secret');

    $user = Auth::user();

    $sso->authenticate(
        new PendingUser(
            identifier: $user->id,
            email: $user->email,
            name: $user->name,
            avatar: $user->avatar_url,
        )
    );
});

Laravel Integration

If you have an existing Laravel application and user base, you can now install Waterhole into your project as a package, and automatically authenticate your users. Currently only Laravel 10 is supported.

Check out the new Laravel Integration docs to learn how to set this up. After installing and configuring Waterhole, setting up the authentication integration is as easy as adding an interface and a trait to your application's User model:

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Waterhole\Auth\AuthenticatesWaterhole;
use Waterhole\Auth\HasWaterholeUser;

class User extends Authenticable implements AuthenticatesWaterhole
{
    use HasWaterholeUser;
}

Upgrading From 0.3

This release contains breaking changes listed in the Release Notes. Before upgrading, you should review this list and make appropriate updates to your customizations.

There are also changes to the Waterhole configuration files. While many of these changes are not required, you may wish to review them and keep your project's configuration files in sync.

One configuration change is required. In the config/waterhole/auth.php file, rename the oauth_providers key to providers:

- 'oauth_providers' => [
+ 'providers' => [

Also, if you are using any auth providers, you will need to change the redirect URLs in config/services.php from /oauth/{provider}/callback to /auth/{provider}/callback:

-    'redirect' => '/oauth/github/callback',
+    'redirect' => '/auth/github/callback',

Now in your composer.json file, change the waterhole/core requirement:

- "waterhole/core": "^0.3"
+ "waterhole/core": "^0.4"

Then run:

composer update waterhole/core --with-dependencies
php artisan migrate
php artisan waterhole:cache:clear

What's Next

The next release, 0.5, will introduce a comprehensive JSON API so you can read and write forum data outside of Waterhole. It will also bring some changes to the extension API to improve performance and stability.