README

Laravel Stronghold is an extended version of Laravel Fortify that adds profile management, social authentication, and enhanced security features to your Laravel application. It provides a robust authentication foundation with OAuth support, new location confirmation, and user profile management out of the box.

Contents

• Installation
• Configuration
• Usage
  • Editing Profile Action
  • Enabling Features
  • OAuth Authentication
  • User Traits
  • Customizing Views
  • Custom New Location Detection
  • Session Status Messages
• License

Installation

You can install the package via composer:

composer require miguilim/laravel-stronghold

Note

If you have Laravel Fortify installed in your composer.json, please remove it as this package extends Fortify's functionality.

After installation, run the install command:

php artisan stronghold:install

This will publish the configuration file, migrations, and action stubs.

Run the migrations:

php artisan migrate

Configuration

First, add the OAuth provider configurations to your config/services.php file:

'github' => [
    'client_id' => env('GITHUB_CLIENT_ID'),
    'client_secret' => env('GITHUB_CLIENT_SECRET'),
    'redirect' => '/oauth/github/callback',
],

'google' => [
    'client_id' => env('GOOGLE_CLIENT_ID'),
    'client_secret' => env('GOOGLE_CLIENT_SECRET'),
    'redirect' => '/oauth/google/callback',
],

// Add other providers as needed...

Then add the corresponding environment variables to your .env file:

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

# Add other providers as needed...

Usage

Editing Profile Action

This package adds an option to the user to upload a profile photo. You need to change the Fortify UpdateUserProfileInformation to support that:

Validator::make($input, [
    'name' => ['required', 'string', 'max:255'],

    'email' => [
        'required',
        'string',
        'email',
        'max:255',
        Rule::unique('users')->ignore($user->id),
    ],

    'photo' => ['nullable', 'file', 'mimes:jpg,jpeg,png,gif', 'max:2048'],
])->validateWithBag('updateProfileInformation');

if (isset($input['photo'])) {
    $user->updateProfilePhoto($input['photo']);
}

if ($input['email'] !== $user->email &&
    $user instanceof MustVerifyEmail) {
    $this->updateVerifiedUser($user, $input);
} else {
    $user->forceFill([
        'name' => $input['name'],
        'email' => $input['email'],
    ])->save();
}

Enabling Features

Configure which features to enable in config/stronghold.php:

'features' => [
    'confirm-new-location',
    'sign-in-notification',
    'socialite',
],

Important

The confirm-new-location feature is not applied when:

• The user has two-factor authentication (2FA) enabled
• The user is logging in via OAuth providers

OAuth Authentication

Users can authenticate using OAuth providers:

/oauth/{provider}         # Redirect to OAuth provider
/oauth/{provider}/callback # Handle OAuth callback

Important

The socialite feature oauth endpoint will: If account and provider account are found - authenticate the user. If account was found but the provider account is not connected - return an error and ask the user to login and connect the provider account from the profile page. If account and provider account were not found - create the account, create the provider account and authenticate the user.

User Traits

Add the provided traits to your User model to enable additional functionality:

use Miguilim\LaravelStronghold\Traits\HasConnectedAccounts;
use Miguilim\LaravelStronghold\Traits\HasProfilePhoto;

class User extends Authenticatable
{
    use HasConnectedAccounts;
    use HasProfilePhoto;

    // Your existing model code...
}

Customizing Views

Register custom views in your FortifyServiceProvider:

use Miguilim\LaravelStronghold\Stronghold;

Stronghold::confirmLocationView(function () {
    return view('auth.confirm-location');
});

Stronghold::profileView(function (array $data) {
    return view('profile.show', $data);
});

Note

It is preferable that if you are using the two factor feature, you set the confirmPassword option to false.

Custom New Location Detection

Define custom logic for detecting new locations:

use Miguilim\LaravelStronghold\Stronghold;

Stronghold::detectNewLocationUsing(function ($request, $user) {
    return true; // true if it is a new location (default is always true)
});

Session Status Messages

To retrieve human-readable session status messages:

$message = Stronghold::getSessionStatusMessage();

This method converts session status keys into localized, human-readable messages for various actions such as password updates, profile changes, two-factor authentication events, and Stronghold-specific events like session logouts or social account connections.

License

Laravel Stronghold is open-sourced software licensed under the MIT license.