php - How do we implement custom API-only authentication in Laravel
Get the solution ↓↓↓This isn't a question so much in need of an answer, but further suggestions and answers and recommendations are welcome. I want to share with the world how I resolved this issue and hope it helps others.
Laravel comes with several pre-designed authentication solutions that you can spin up with a few artisan commands. These include:
- standard users table authentication
- OAuth2 (via the Laravel Passport package)
- Social media based authentication (via the Laravel Socialite package)
As useful as all of these are, in this age of micro-services, Laravel doesn't provide much in the way of an out-of-the-box bootstrap for API-only authentication using custom APIs.
I was faced with this problem several months ago and I searched Google and Stackoverflow for an answer. I found helpful articles which helped to point the way, and these are cited. It took some effort to understand how to glue them together and step-debugging to iron out the kinks.
The answer is provided in the hope that it helps others - and myself, where I have to do the same thing again in the future.
Assumptions and Scope:
- you've created your own API like https://example.com/login and https://example.com/logout
- you're running a website that requires authentication, but not via models and tables or social media
- your API manages interactions with tables, including user-login/logout
- you use the Laravel Passport add-on for OAuth2 authentication (acknowledgements to @ShuvoJoseph for bringing this to my attention)
Answer
Solution:
The solution involves seven PHP files
- app/Http/Controllers/HomeController.php - homepage controller; the destination for an authenticated user
- app/Providers/ApiUserProvider.php - a custom provider to bootstrap and register the logged-in user, and implements the interface Illuminate\Contracts\Auth\UserProvider
- app/CoreExtensions/SessionGuardExtended.php - custom guard-controller to log-in the user and receives the authentication values and stores them in session array; extends class Illuminate\Auth\SessionGuard
- app/ApiUser - if you're using OAuth2 (Laravel's Passport); custom user class that exposes the OAuth access_token; extends Illuminate\Auth\GenericUser and implements the interface Illuminate\Contracts\Auth\Authenticatable
- config/auth.php - the auth config which instructs the Auth() facade to return the custom session guard
- app/Providers/AuthServiceProvider.php - the auth bootstrap
- app/Providers/AppServiceProvider.php - the main application bootstrap
Source research/investigation material are cited for you to investigate for yourself and comprehend the background context to their existence. I make no claims to be a genius who created the solution from scratch through my own mojo, but rather that - like all innovators - I build on the efforts of others. The unique selling point of my article is that I provide a complete packaged solution, whereas the cited sources provide solutions to niche parts of the overall answer. Together, after much trial and error, they helped me to form a complete solution.
A really useful article to understands how config/auth.php affects execution in AuthManager.php is https://www.2hatslogic.com/blog/laravel-custom-authentication/
No code modifications are made to the following, but they're included to acknowledge the role they play and their importance in the process:
- vendor/laravel/framework/src/Illuminate/Auth/AuthManager.php - main authorization factory manager
- Auth() facade - returns the shrink-wrapped Illuminate\Auth\SessionGuard class instance by default, unless it's instructed to do otherwise through the config/auth.php file - Auth() is used ubiquitously throughout Laravel code to retrieve the session guard
The Code
app/Http/Controllers/HomeController.php
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
/**
* Handles and manages the home-page
*
* @category controllers
*/
class HomeController extends Controller
{
/**
* Create a new controller instance.
*
* @return void
*/
public function __construct()
{
$this->middleware('auth');
}
public function index()
{
blah
}
... other methods ...
}
app/Providers/ApiUserProvider.php
Sources:
- Using Laravel 5.8 authentication with external JSON API (Creating own ServiceProvider)
- https://laracasts.com/discuss/channels/laravel/replacing-the-laravel-authentication-with-a-custom-authentication
- Custom user authentication base on the response of an API call
<?php
namespace App\Providers;
use Illuminate\Contracts\Auth\UserProvider;
use Illuminate\Contracts\Auth\Authenticatable as UserContract;
use App\ApiUser;
/**
* Delegates API user login and authentication
*
* @category providers
*/
class ApiUserProvider implements UserProvider
{
/**
* Custom API Handler
* Used to request API and capture responses
*
* @var \Path\To\Your\Internal\Api\Handler
*/
private $_oApi = null;
/**
* POST request to API
*
* @param string $p_url Endpoint URL
* @param array $p_arrParam Parameters
* @param boolean $p_isOAuth2 Is OAuth2 authenticated request? [Optional, Default=True]
*
* @return array
*/
private function _post(string $p_url, array $p_arrParam, bool $p_isOAuth2=true)
{
if (!$this->_oApi) {
$this->_oApi = new \Path\To\Your\Internal\Api\Handler();
}
$arrResponse = $this->_oApi->post($p_url, $p_arrParam, $p_isOAuth2);
return $arrResponse;
}
/**
* GET request to API
*
* @param string $p_url Endpoint URL
* @param array $p_arrParam Parameters [Optional, Default = array()]
*
* @return array
*/
private function _get(string $p_url, array $p_arrParam=[], bool $p_isOAuth2=true)
{
if (!$this->_oApi) {
$this->_oApi = new \Path\To\Your\Internal\Api\Handler();
}
$arrResponse = $this->_oApi->get($p_url, $p_arrParam);
return $arrResponse;
}
/**
* Retrieve a user by the given credentials.
*
* @param array $p_arrCredentials
*
* @return \Illuminate\Contracts\Auth\Authenticatable|null
*/
public function retrieveByCredentials(array $p_arrCredentials)
{
$arrResponse = $this->_post('/login', $p_arrCredentials, false);
if ( $arrResponse['result'] ) {
$arrPayload = array_merge(
$arrResponse['data'],
$p_arrCredentials
);
return $this->getApiUser($arrPayload);
}
}
/**
* Retrieve a user by their unique identifier.
*
* @param mixed $p_id
*
* @return \Illuminate\Contracts\Auth\Authenticatable|null
*/
public function retrieveById($p_id)
{
$arrResponse = $this->_get("user/id/{$p_id}");
if ( $arrResponse['result'] ) {
return $this->getApiUser($arrResponse['data']);
}
}
/**
* Validate a user against the given credentials.
*
* @param \Illuminate\Contracts\Auth\Authenticatable $p_oUser
* @param array $p_arrCredentials
*
* @return bool
*/
public function validateCredentials(UserContract $p_oUser, array $p_arrCredentials)
{
return $p_oUser->getAuthPassword() == $p_arrCredentials['password'];
}
/**
* Get the api user.
*
* @param mixed $p_user
*
* @return \App\Auth\ApiUser|null
*/
protected function getApiUser($p_user)
{
if ($p_user !== null) {
return new ApiUser($p_user);
}
return null;
}
protected function getUserById($id)
{
$user = [];
foreach ($this->getUsers() as $item) {
if ($item['account_id'] == $id) {
$user = $item;
break;
}
}
return $user ?: null;
}
protected function getUserByUsername($username)
{
$user = [];
foreach ($this->getUsers() as $item) {
if ($item['email_address'] == $username) {
$user = $item;
break;
}
}
return $user ?: null;
}
/**
* The methods below need to be defined because of the Authenticatable contract
* but need no implementation for 'Auth::attempt' to work and can be implemented
* if you need their functionality
*/
public function retrieveByToken($identifier, $token) { }
public function updateRememberToken(UserContract $user, $token) { }
}
app/CoreExtensions/SessionGuardExtended.php
Sources:
- Extending Laravel 5.2 SessionGuard
- Using Laravel 5.8 authentication with external JSON API (Creating own ServiceProvider)
<?php
namespace App\CoreExtensions;
use Illuminate\Auth\SessionGuard;
use Illuminate\Contracts\Auth\Authenticatable;
/**
* Extended SessionGuard() functionality
* Provides added functionality to store the OAuth tokens in the session for later use
*
* @category guards
*
* @see https://stackoverflow.com/questions/36087061/extending-laravel-5-2-sessionguard
*/
class SessionGuardExtended extends SessionGuard
{
/**
* Log a user into the application.
*
* @param \Illuminate\Contracts\Auth\Authenticatable $p_oUser
* @param bool $p_remember
* @return void
*/
public function login(Authenticatable $p_oUser, $p_remember = false)
{
parent::login($p_oUser, $p_remember);
/**
* Writing the OAuth tokens to the session
*/
$key = 'authtokens';
$this->session->put(
$key,
[
'access_token' => $p_oUser->getAccessToken(),
'refresh_token' => $p_oUser->getRefreshToken(),
]
);
}
/**
* Log the user out of the application.
*
* @return void
*/
public function logout()
{
parent::logout();
/**
* Deleting the OAuth tokens from the session
*/
$this->session->forget('authtokens');
}
}
app/ApiUser
Sources:
- Using Laravel 5.8 authentication with external JSON API (Creating own ServiceProvider) *https://laracasts.com/discuss/channels/laravel/replacing-the-laravel-authentication-with-a-custom-authentication
- Custom user authentication base on the response of an API call
<?php
namespace App;
use Illuminate\Auth\GenericUser;
use Illuminate\Contracts\Auth\Authenticatable as UserContract;
class ApiUser extends GenericUser implements UserContract
{
/**
* Returns the OAuth access_token
*
* @return mixed
*/
public function getAccessToken()
{
return $this->attributes['access_token'];
}
public function getRefreshToken()
{
return $this->attributes['refresh_token'];
}
}
app/Providers/AuthServiceProvider.php
<?php
namespace App\Providers;
use Illuminate\Support\Facades\Auth;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
class AuthServiceProvider extends ServiceProvider
{
/**
* Register any authentication / authorization services.
*
* @return void
*/
public function boot()
{
$this->registerPolicies();
Auth::provider('frank_sinatra', function ($app, array $config) {
// Return an instance of Illuminate\Contracts\Auth\UserProvider...
return new ApiUserProvider();
});
}
}
app/Providers/AppServiceProvider.php
Sources:
Note:
There is a couple of nuanced issues regarding the change to coding in this PHP file. If you want to understand more, look at vendor/laravel/framework/src/Illuminate/Auth/AuthManager.php, AuthManager::resolve() in particular.
- References to config/auth.php 'session' and 'token' are served by hard-coded methods AuthManager::createSessionDriver() and AuthManager::createTokenDriver() (Tell me please if you know of a way to extend AuthManager.php in the app)
- AppServiceProvider.php to the rescue! Custom guards can be registered in AppServiceProvider::boot() and intercepted before the default code can be executed.
- I'm OK with point 2 above, but couldn't we do something clever like return the custom session-guard name or instance from AppServiceProvider, have setCookieJar(), setDispatcher(), setRequest() in a specialized public method in AuthManager.php, which can be hooked into AppServiceProvider.php or driven by config/auth.php to execute after creating the custom session-guard in AuthManager.php?
- Without the cookies or sessions, the user's identity isn't preserved through the redirect. The only way to resolve this is to include the setCookieJar(), setDispatcher() and setRequest() in AppServiceProvider within our current solution.
<?php
namespace App\Providers;
use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Facades\Auth;
use App\CoreExtensions\SessionGuardExtended;
class AppServiceProvider extends ServiceProvider
{
/**
* Register any application services.
*
* @return void
*/
public function register()
{
//
}
/**
* Bootstrap any application services.
*
* @see https://stackoverflow.com/questions/36087061/extending-laravel-5-2-sessionguard
*
* @return void
*/
public function boot()
{
/**
* Extending Illuminate\Auth\SessionGuard()
* This is so we can store the OAuth tokens in the session
*/
Auth::extend(
'sessionExtended',
function ($app) {
$guard = new SessionGuardExtended(
'sessionExtended',
new ApiUserProvider(),
app()->make('session.store'),
request()
);
// When using the remember me functionality of the authentication services we
// will need to be set the encryption instance of the guard, which allows
// secure, encrypted cookie values to get generated for those cookies.
if (method_exists($guard, 'setCookieJar')) {
$guard->setCookieJar($this->app['cookie']);
}
if (method_exists($guard, 'setDispatcher')) {
$guard->setDispatcher($this->app['events']);
}
if (method_exists($guard, 'setRequest')) {
$guard->setRequest($this->app->refresh('request', $guard, 'setRequest'));
}
return $guard;
}
);
}
}
config/auth.php
Sources:
<?php
return [
/*
|
How To Use This Solution
Very simple. There's no change in the overall approach. In other words, we use the Auth() facade.
When logging in with your custom API{-code-8}
{-code-9}
When logging out with your custom API{-code-10}
{-code-11}
Answer
Answer
Answer
Share solution ↓
Additional Information:
Link To Answer People are also looking for solutions of the problem: attempt to read property "id" on null
Didn't find the answer?
Our community is visited by hundreds of web development professionals every day. Ask your question and get a quick answer for free.
Similar questions
Find the answer in similar questions on our website.
Write quick answer
Do you know the answer to this question? Write a quick response to it. With your help, we will make our community stronger.