PHPackages                             metrakit/extended-eloquent-oauth - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. metrakit/extended-eloquent-oauth

ActiveLibrary[Authentication & Authorization](/categories/authentication)

metrakit/extended-eloquent-oauth
================================

Stupid simple OAuth authentication with Laravel and Eloquent

v5.0.1(11y ago)1784MITPHPPHP >=5.4.0

Since Dec 20Pushed 11y ago1 watchersCompare

[ Source](https://github.com/Metrakit/extended-eloquent-oauth)[ Packagist](https://packagist.org/packages/metrakit/extended-eloquent-oauth)[ RSS](/packages/metrakit-extended-eloquent-oauth/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (6)Versions (21)Used By (0)

Eloquent OAuth
==============

[](#eloquent-oauth)

[![Code Climate](https://camo.githubusercontent.com/e941c25f94e8bad1bf7fa685f0b7b8bf0f34e1a3eb0008f0aa3e6c88d34db987/68747470733a2f2f636f6465636c696d6174652e636f6d2f6769746875622f6164616d77617468616e2f656c6f7175656e742d6f617574682f6261646765732f6770612e737667)](https://codeclimate.com/github/adamwathan/eloquent-oauth)[![Build Status](https://camo.githubusercontent.com/5fd421e9bdcde2ad501881b754d9b4c8c2da52617740067d43532dc96227f142/68747470733a2f2f6170692e7472617669732d63692e6f72672f6164616d77617468616e2f656c6f7175656e742d6f617574682e737667)](https://travis-ci.org/adamwathan/eloquent-oauth)

> Note: Check the [Laravel 4 branch](https://github.com/adamwathan/eloquent-oauth/tree/laravel-4) if you are using Laravel 4.

Eloquent OAuth is a package for Laravel 5 designed to make authentication against various OAuth providers *ridiculously* brain-dead simple. Specify your client IDs and secrets in a config file, run a migration and after that it's just two method calls and you have OAuth integration.

#### Video Walkthrough

[](#video-walkthrough)

[![Screenshot](https://cloud.githubusercontent.com/assets/4323180/6274884/ac824c48-b848-11e4-8e4d-531e15f76bc0.png)](https://vimeo.com/120085196)

#### Basic example

[](#basic-example)

```
// Redirect to Facebook for authorization
Route::get('facebook/authorize', function() {
    return OAuth::authorize('facebook');
});

// Facebook redirects here after authorization
Route::get('facebook/login', function() {

    // Automatically log in existing users
    // or create a new user if necessary.
    OAuth::login('facebook');

    // Current user is now available via Auth facade
    $user = Auth::user();

    return Redirect::intended();
});
```

#### Supported Providers

[](#supported-providers)

- Facebook
- GitHub
- Google
- LinkedIn
- Instagram
- SoundCloud

> Feel free to open an issue if you would like support for a particular provider, or even better, submit a pull request.

Installation
------------

[](#installation)

#### Add this package using Composer

[](#add-this-package-using-composer)

From the command line inside your project directory, simply type:

`composer require adamwathan/eloquent-oauth`

(Or you can manually edit `composer.json` by adding the following line under the `"require"` section:

`"adamwathan/eloquent-oauth": "~5.0"`

...then run `composer update` to download the package to your vendor directory.)

#### Update your config

[](#update-your-config)

Add the service provider to the `providers` array in `config/app.php`:

```
'providers' => [
    // ...
    'AdamWathan\EloquentOAuth\EloquentOAuthServiceProvider',
    // ...
]
```

Add the facade to the `aliases` array in `config/app.php`:

```
'aliases' => [
    // ...
    'OAuth' => 'AdamWathan\EloquentOAuth\Facades\OAuth',
    // ...
]
```

#### Publish the package configuration

[](#publish-the-package-configuration)

Publish the configuration file and migrations by running the provided console command:

`php artisan eloquent-oauth:install`

Next, re-migrate your database:

`php artisan migrate`

> If you need to change the name of the table used to store OAuth identities, you can do so in the `eloquent-oauth` config file.

#### Configure the providers

[](#configure-the-providers)

Update your app information for the providers you are using in `config/eloquent-oauth.php`:

```
'providers' => [
    'facebook' => [
        'id' => '12345678',
        'secret' => 'y0ur53cr374ppk3y',
        'redirect' => 'https://example.com/facebook/login'),
        'scope' => [],
    ]
]
```

> Each provider is preconfigured with the scope necessary to retrieve basic user information and the user's email address, so the scope array can usually be left empty unless you need specific additional permissions. Consult the provider's API documentation to find out what permissions are available for the various services.

All done!

> Eloquent OAuth is designed to integrate with Laravel's Eloquent authentication driver, so be sure you are using the `eloquent` driver in `app/config/auth.php`. You can define your actual `User` model however you choose and add whatever behavior you need, just be sure to specify the model you are using with its fully qualified namespace in `app/config/auth.php` as well.

Usage
-----

[](#usage)

Authentication against an OAuth provider is a multi-step process, but I have tried to simplify it as much as possible.

### Authorizing with the provider

[](#authorizing-with-the-provider)

First you will need to define the authorization route. This is the route that your "Login" button will point to, and this route redirects the user to the provider's domain to authorize your app. After authorization, the provider will redirect the user back to your second route, which handles the rest of the authentication process.

To authorize the user, simply return the `OAuth::authorize()` method directly from the route.

```
Route::get('facebook/authorize', function() {
    return OAuth::authorize('facebook');
});
```

### Authenticating within your app

[](#authenticating-within-your-app)

Next you need to define a route for authenticating against your app with the details returned by the provider.

For basic cases, you can simply call `OAuth::login()` with the provider name you are authenticating with. If the user rejected your application, this method will throw an `ApplicationRejectedException` which you can catch and handle as necessary.

The `login` method will create a new user if necessary, or update an existing user if they have already used your application before.

Once the `login` method succeeds, the user will be authenticated and available via `Auth::user()` just like if they had logged in through your application normally.

```
use \AdamWathan\EloquentOAuth\Exceptions\ApplicationRejectedException;
use \AdamWathan\EloquentOAuth\Exceptions\InvalidAuthorizationCodeException;

Route::get('facebook/login', function() {
    try {
        OAuth::login('facebook');
    } catch (ApplicationRejectedException $e) {
        // User rejected application
    } catch (InvalidAuthorizationCodeException $e) {
        // Authorization was attempted with invalid
        // code,likely forgery attempt
    }

    // Current user is now available via Auth facade
    $user = Auth::user();

    return Redirect::intended();
});
```

If you need to do anything with the newly created user, you can pass an optional closure as the second argument to the `login` method. This closure will receive the `$user` instance and a `ProviderUserDetails`object that contains basic information from the OAuth provider, including:

- User ID
- Nickname
- First Name
- Last Name
- Email
- Image URL
- Access Token

```
OAuth::login('facebook', function($user, $details) {
    $user->nickname = $details->nickname;
    $user->name = $details->firstName . ' ' . $details->lastName;
    $user->profile_image = $details->imageUrl;
    $user->save();
});
```

> Note: The Instagram API does not allow you to retrieve the user's email address, so unfortunately that field will always be `null` for the Instagram provider.

### Advanced: Storing additional data

[](#advanced-storing-additional-data)

Remember: One of the goals of the Eloquent OAuth package is to normalize the data received across all supported providers, so that you can count on those specific data items (explained above) being available in the `$details` object.

But, each provider offers its own sets of additional data. If you need to access or store additional data beyond the basics of what Eloquent OAuth's default `ProviderUserDetails` object supplies, you need to do two things:

1. Request it from the provider, by extending its scope:

    Say for example we want to collect the user's gender when they login using Facebook.

    In the `config/eloquent-oauth.php` file, set the `[scope]` in the `facebook` provider section to include the `public_profile` scope, like this:

    ```
       'scope' => ['email', 'public_profile'],
    ```

> For available scopes with each provider, consult that provider's API documentation.

> NOTE: By increasing the scope you will be asking the user to grant access to additional information. They will be informed of the scopes you're requesting. If you ask for too much unnecessary data, they may refuse. So exercise restraint when requesting additional scopes.

2. Now where you do your `OAuth::login`, store the to your `$user` object by accessing the `$details->raw()['KEY']` data:

```
       OAuth::login('facebook', function($user, $details) (
           $user->gender = $details->raw()['gender']; // Or whatever the key is
           $user->save();
       });
```

> TIP: You can see what the available keys are by testing with `dd($details->raw());` inside that same closure.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity15

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 93.4% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~40 days

Recently: every ~8 days

Total

13

Last Release

4046d ago

Major Versions

v0.7.0 → v4.0.02015-02-23

v4.0.0 → v5.0.02015-03-18

PHP version history (2 changes)v0.1PHP >=5.3.0

v0.7.0PHP >=5.4.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/acdfe781de2786faf12c4e84fc09f182618f4964ec049c66852363c1ce516c77?d=identicon)[Metrakit](/maintainers/Metrakit)

---

Top Contributors

[![adamwathan](https://avatars.githubusercontent.com/u/4323180?v=4)](https://github.com/adamwathan "adamwathan (171 commits)")[![drbyte](https://avatars.githubusercontent.com/u/404472?v=4)](https://github.com/drbyte "drbyte (3 commits)")[![knvpk](https://avatars.githubusercontent.com/u/6078669?v=4)](https://github.com/knvpk "knvpk (3 commits)")[![Metrakit](https://avatars.githubusercontent.com/u/3305600?v=4)](https://github.com/Metrakit "Metrakit (2 commits)")[![syphernl](https://avatars.githubusercontent.com/u/639906?v=4)](https://github.com/syphernl "syphernl (2 commits)")[![cmgmyr](https://avatars.githubusercontent.com/u/4693481?v=4)](https://github.com/cmgmyr "cmgmyr (1 commits)")[![schmitzc](https://avatars.githubusercontent.com/u/10464?v=4)](https://github.com/schmitzc "schmitzc (1 commits)")

### Embed Badge

![Health badge](/badges/metrakit-extended-eloquent-oauth/health.svg)

```
[![Health](https://phpackages.com/badges/metrakit-extended-eloquent-oauth/health.svg)](https://phpackages.com/packages/metrakit-extended-eloquent-oauth)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[laragear/two-factor

On-premises 2FA Authentication for out-of-the-box.

339785.3k8](/packages/laragear-two-factor)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[alajusticia/laravel-logins

Session management in Laravel apps, user notifications on new access, support for multiple separate remember tokens, IP geolocation, User-Agent parser

2011.0k](/packages/alajusticia-laravel-logins)[flarum/core

Delightfully simple forum software.

211.3M1.9k](/packages/flarum-core)[truckersmp/steam-socialite

Laravel Socialite provider for Steam OpenID.

1516.7k](/packages/truckersmp-steam-socialite)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)