ncit/efaas-socialite

eFaas Provider for Laravel Socialite

1.0.0 2023-07-06 04:08 UTC

Requires

• php: >=7.2
• illuminate/http: ^9.0|^10.0
• illuminate/support: ^5.6|^6.0|^7.0|^8.0|^9.0|^10.0
• laravel/socialite: ~3.3|~4.0|~5.0

Requires (Dev)

• orchestra/testbench: ^4.0
• phpunit/phpunit: ^8.0

MIT

• Ahmed Shifau

README

Laravel Socialite Provider for eFaas.

Installation

You can install the package via composer:

composer require ncit/efaas-socialite

Laravel 5.5 and above uses Package Auto-Discovery, so doesn't require you to manually add the ServiceProvider.

After updating composer, add the ServiceProvider to the providers array in config/app.php

Ncit\Efaas\Socialite\Providers\EfaasSocialiteServiceProvider::class,

Add configuration to config/services.php

'efaas' => [    
    'client_id' => env('EFAAS_CLIENT_ID'),  
    'client_secret' => env('EFAAS_CLIENT_SECRET'),  
    'redirect' => env('EFAAS_CLIENT_REDIRECT_URI'),
    'server_url' => env('EFAAS_URL', 'https://efaas.gov.mv/connect'),
],

Usage

You should now be able to use the provider like you would regularly use Socialite (assuming you have the facade installed): Refer to the Official Social Docs for more info.

Warning: If you get 403 Forbidden error when your Laravel app makes requests to the eFaas authorization endpoints, request NCIT to whitelist your server IP.

//efaas default scopes are openid and efaas.profile
return Socialite::driver('efaas')->redirect();

//to get extra scopes pass other scopes on scopes methods
return Socialite::driver('efaas')->scopes([
    'openid',
    'efaas.profile',
    'efaas.email',
    'efaas.mobile',
    'efaas.passport_number',
    'efaas.country',
    'efaas.work_permit_status',
    'efaas.photo'
])->redirect();

and in your callback handler, you can access the user data like so.

$efaasUser = Socialite::driver('efaas')->user();
$accessToken = $efaasUser->token;

Logging out the eFaas User

In your Laravel logout redirect, redirect with the provider logOut() method using the access token saved during login

return Socialite::driver('efaas')->logOut($access_token, $post_logout_redirect_url);

Using eFaas One-tap Login

This package will automatically add an /efaas-one-tap-login endpoint to your web routes which will redirect to eFaas with the eFaas login code.

Sometimes you may wish to customize the routes defined by the Efaas Provider. To achieve this, you first need to ignore the routes registered by Efaas Provider by adding EfaasProvider::ignoreRoutes to the register method of your application's AppServiceProvider:

use Ncit\Efaas\EfaasProvider;

/**
 * Register any application services.
 */
public function register(): void
{
    EfaasProvider::ignoreRoutes();
}

Then, you may copy the routes defined by Efaas Provider in its routes file to your application's routes/web.php file and modify them to your liking:

Route::group([
    'as' => 'efaas.',
    'namespace' => '\Ncit\Efaas\Http\Controllers',
], function () {
    // Efaas routes...
});

Authenticating from mobile apps

To authenticate users from mobile apps, redirect to the eFaas login screen through a Web View on the mobile app. Then intercept the code (authorization code) from eFaas after they redirect you back to your website after logging in to eFaas.

Once your mobile app receives the auth code, send the code to your API endpoint. You can then get the eFaas user details from your server side using the auth code as follows:

$efaas_user = Socialite::driver('efaas')->userFromCode($code);

After you receive the eFaas user, you can then issue your own access token or API key according to whatever authentication scheme you use for your API.

Changing the eFaas login prompt behaviour

The eFaas login prompt behaviour can be customized by modifying the prompt option on your redirect request

return Socialite::driver('efaas')->with(['prompt' => 'select_account'])->redirect();

The available prompt options are:

Available properties for eFaas User

$id_number = $efaasUser->username;

All Available eFaas data fields

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [e-mail] instead of using the issue tracker.

Credits

• Javaabu Pvt. Ltd.
• Arushad Ahmed (@dash8x)
• Mohamed Jailam
• All Contributors

License

The MIT License (MIT). Please see License File for more information.