README

Avonez Auth Client adds an OAuth sign-in flow for Avonez accounts to a Laravel application. It redirects users to Avonez, handles the callback, synchronizes the account and its organizations, and signs the user into Laravel.

Requirements

PHP 8.3 or later
Laravel 12 or 13
A configured Avonez OAuth client

Installation

Install the package with Composer:

composer require avonez-tech/avonez-auth-client

Laravel discovers the service provider automatically. The package registers its routes and migrations and merges its default configuration.

Configuration

Add your OAuth client credentials and callback URL to the application's .env file:

AVONEZ_AUTH_CLIENT_ID=your-client-id
AVONEZ_AUTH_CLIENT_SECRET=your-client-secret
AVONEZ_AUTH_REDIRECT_URI="${APP_URL}/auth"

The package reads these settings from config/avonez-auth-client.php:

'client_id' => env('AVONEZ_AUTH_CLIENT_ID'),
'client_secret' => env('AVONEZ_AUTH_CLIENT_SECRET'),
'redirect' => env('AVONEZ_AUTH_REDIRECT_URI'),
'host' => 'https://account.avonez.com',
'scope' => 'user:read organizations:read',
'user-model' => \AvonezAuthClient\Models\User::class,
'organization-model' => \AvonezAuthClient\Models\Organization::class,
'branch-model' => \AvonezAuthClient\Models\Branch::class,
'organization-user-model' => \AvonezAuthClient\Models\OrganizationUser::class,
'allow-registration' => env('AVONEZ_AUTH_ALLOW_REGISTRATION', true),
'allow-personal-organization' => env('AVONEZ_AUTH_ALLOW_PERSONAL_ORGANIZATION', true),

Set AVONEZ_AUTH_ALLOW_REGISTRATION=false to prevent creation of new local users while still allowing existing users to sign in. Set AVONEZ_AUTH_ALLOW_PERSONAL_ORGANIZATION=false to omit personal organizations during organization synchronization.

Publish the config file to customize the OAuth server host, requested scopes, or model classes:

php artisan vendor:publish --tag=avonez-auth-client-config

The default scope is user:read organizations:read. The package uses the configured user-model to create or update users, and the configured organization, branch, and pivot models when synchronizing memberships. A custom user model must extend AvonezAuthClient\Models\User.

The OAuth server must provide /oauth/authorize, /oauth/token, and /api/user. When the access token includes the organizations:read scope, the package also requests /api/organizations and synchronizes organizations, branches, and user memberships.

User model and database

By default, the package authenticates users using AvonezAuthClient\Models\User, which uses the application's users table. Configure the application's users auth provider to use the same model configured as user-model so Laravel can restore the authenticated user from the session:

// config/auth.php
'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => AvonezAuthClient\Models\User::class,
    ],
],

The package migrations are loaded automatically. Review them before running them, especially if your application already has user data: the user migration assumes a users table exists, adds Avonez identity and token columns, makes email nullable, and drops password, remember_token, and email_verified_at. Its rollback does not restore those dropped columns. Back up your database and adapt or publish the migrations if those changes do not suit your application.

The organizations table is created only when the configured scope contains organization, so keep the default organization scope (or another scope containing organization) configured before running migrations. The package also creates the branches table and the organization_user pivot table. Organization records include their Avonez ID, name, slug, type, status, contact details, website, and metadata. Branch records belong to organizations and include their Avonez ID, name, slug, address, status, contact details, and metadata. Memberships can include a branch and designation.

The User model exposes organizations() and branches() relationships, and the Organization model exposes branches() and users() relationships. Access and refresh tokens are stored on the user record and hidden from its serialized attributes; user and organization metadata are cast to arrays.

Migration helpers

The package registers Blueprint helpers for adding foreign keys that follow the configured model classes:

use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::table('projects', function (Blueprint $table) {
    $table->belongsToOrganization();
    $table->belongsToUser(nullable: true);
    $table->belongsToBranch();
});

belongsToOrganization(), belongsToUser(), and belongsToBranch() each create the corresponding organization_id, user_id, or branch_id foreign key. They use the configured organization, user, and branch models. By default, the column is required and cascades on delete; pass nullable: true to make it nullable and set the foreign key to null when the related record is deleted.

Sign-in flow

Send users to /login to start Avonez authorization. After consent, Avonez returns them to /auth; the package validates the OAuth state, retrieves the profile, updates the local user (and organizations when permitted), logs the user in, and redirects to the intended URL or /. Both routes use Laravel's web middleware, which provides the session needed for OAuth state validation. Requests to /register are permanently redirected to /login.

The routes are registered by the package and do not require a facade call:

<a href="{{ url('/login') }}">Sign in with Avonez</a>

Publishing resources

The package publishes configuration and migrations. Publish all resources with:

php artisan vendor:publish --tag=avonez-auth-client

Or publish an individual resource:

php artisan vendor:publish --tag=avonez-auth-client-config
php artisan vendor:publish --tag=avonez-auth-client-migrations

Development

Run the package checks locally:

composer install
composer test

See the contribution guide for contribution instructions and the security policy to report a vulnerability.

License

Avonez Auth Client is open-source software licensed under the MIT License.

avonez-tech / avonez-auth-client

Package info

Security

Fund package maintenance!

Statistics