Oauth 4 Laravel Laravel Package

Getting Started

Install into a Laravel 4 app

composer require artdarek/oauth-4-laravel

Register the service provider and facade in app/config/app.php:

'providers' => [
    // ...
    'Artdarek\OAuth\OAuthServiceProvider',
],

'aliases' => [
    // ...
    'OAuth' => 'Artdarek\OAuth\Facade\OAuth',
],

Publish the package config so you have a place to drop provider credentials:

php artisan config:publish artdarek/oauth-4-laravel

This creates app/config/packages/artdarek/oauth-4-laravel/config.php. Inside, fill the consumers block for every provider you intend to use (Facebook, Google, GitHub, Twitter, LinkedIn, etc.) with client_id, client_secret, scope, and redirect, and leave storage pointing at Session for now.

Where to look first

1. config.php – the whole thing is driven off consumers; get this right before writing any routes.
2. The facade call OAuth::consumer('Provider') – this returns the underlying lusitanian/oauth consumer object, and almost everything you do is a method on it. The upstream lusitanian/oauth docs (v0.3–0.4 series) are effectively the API reference for this package.
3. OAuth::consumer(...)->getStorage() – the token store; you’ll touch this on every callback.

First use case: social login in three routes

Create the OAuth application on the provider’s developer console, set the callback URL to something like http://myapp.local/login/facebook/callback, and paste the credentials into config. Then:

// routes.php
Route::get('login/{provider}', function ($provider) {
    $url = OAuth::consumer($provider)->getAuthorizationUri();
    return Redirect::away($url);
});

Route::get('login/{provider}/callback', function ($provider) {
    $code = Input::get('code');
    $token = OAuth::consumer($provider)->requestAccessToken($code);

    // Persist the token, or hit the provider's user endpoint to identify them
    return Redirect::to('dashboard');
});

That’s the entire happy path. Everything else is branching off those two calls.

Implementation Patterns

Token lifecycle is your responsibility. The package does not save tokens for you in a way that survives a real user session. The idiomatic pattern is: on callback, requestAccessToken($code), then take $token->getAccessToken() (and getRefreshToken() where available) and write it to your own users / oauth_accounts table. Rebuild the token later via

$token = OAuth::consumer('Facebook')->getStorage()->retrieveAccessToken('Facebook');

if you’re content to let the default Session storage key it for the current browser, but for anything multi-device or queued, use your own storage.

Detect OAuth1 vs OAuth2 in routing. The flow differs: OAuth2 gives you code in the query string, OAuth1 gives you oauth_token / oauth_verifier. A common pattern is a single callback controller that branches:

if (Input::has('oauth_token')) {
    $token = OAuth::consumer($provider)->requestAccessToken();
} else {
    $token = OAuth::consumer($provider)->requestAccessToken(Input::get('code'));
}

requestAccessToken() with no argument works for OAuth1 (it reads from the current request), which is a genuinely useful convenience.

Swap storage per consumer. storage in config accepts a class name; the package ships a Session store but you can point it at an implementation of OAuth\Common\Storage\TokenStorageInterface. If you’re already persisting tokens yourself, keep the default and treat storage as a short-lived scratchpad during the callback only.

Wrap every provider call in try/catch. The underlying library throws OAuth\Common\Http\Exception\TokenResponseException on bad codes and OAuth\Common\Exception\Exception more generally. Denied permissions come back as an error query param rather than a code, so check Input::has('error') before calling requestAccessToken() — otherwise you get a hard failure on user cancel.

Use scopes at the config level, not in code. The scope array in consumers is what getAuthorizationUri() bakes into the redirect. Changing scopes later means asking for re-consent, so set them generously on day one. Requesting incremental scopes at runtime is possible via the consumer’s getAuthorizationUri() overload but is fiddly and provider-specific.

For a "connect your GitHub account" feature (as opposed to login), the pattern is the same two routes, but on callback you associate the returned provider user ID with the currently authenticated user rather than starting a session. Keep the login and link flows in separate route groups to avoid accidentally logging the wrong account in.

Gotchas and Tips

This is a Laravel 4 package and effectively a historical artifact. It targets PHP 5.3–5.6 era Laravel 4 and the lusitanian/oauth 0.x branch. It will not install cleanly on Laravel 5+ and has been superseded by laravel/socialite. If you are maintaining an existing L4 app, fine — if you’re starting fresh, use Socialite. A lot of the pain below disappears there.

The redirect URI must match byte-for-byte. Providers compare the redirect_uri sent at authorization time with the one sent at token exchange. If config has a trailing slash or http:// vs https:// mismatch, you get an opaque invalid-grant error from the provider, not from this package. Debug with OAuth::consumer('X')->getAuthorizationUri() and read the actual query string.

No CSRF protection on the state parameter. The package does not generate or verify state for you. Store a random value in your session before redirecting and compare it in the callback. Skipping this is a real vulnerability for OAuth2 providers that support state.

The default Session storage loses tokens silently. It’s keyed per consumer and lives in the user’s session — if you use Auth::login() and the session regenerates, tokens can vanish. Don’t rely on it between requests; treat it as valid only within the callback request.

Config caching doesn’t exist in L4, but config publishing does. If you edit the package’s config rather than the published one in app/config/packages/, your changes get overwritten on update. Always edit the published copy. Similarly, composer update can bump lusitanian/oauth out from under you and change method signatures — pin it.

Provider quirks live upstream, not here. This package is a thin wrapper; when Google changes a token endpoint or Facebook renames a field, you fix it by updating lusitanian/oauth or overriding the consumer. The facade exposes OAuth::consumer() returning the raw object, so you can subclass and register a custom consumer via the service factory if you need to patch a specific provider.

Extension point: the service factory. OAuth::consumer($name) resolves through an internal ServiceFactory. If you need a provider the package doesn’t list, or a custom HTTP client (useful for proxied or test HTTP), that’s the place to hook in — you can instantiate \OAuth\ServiceFactory yourself and build consumers directly, bypassing the facade entirely while still using the config for credentials.

Debugging: log the raw URLs. When a callback fails, the most useful log lines are the authorization URI you redirected to and the raw Input::all() on the callback. Most “it doesn’t work” cases are a missing code because the user denied, a scope name the provider doesn’t recognize (which often silently drops and produces a token with no permissions), or a clock skew on OAuth1 signatures — the latter shows up as a signature mismatch that is maddening to diagnose without the raw request.