Tutorials: Integrating OAuth2 Providers

├─ Registration
├─ Authentication
├─ Getting Remote Resources
└─ Handling Errors

Framework uses OAuth2 Client API to integrate OAuth2 providers based on IETF standards instead of resorting to official PHP drivers provided by vendors (often bloated and overprogrammed). This process is achieved in three steps:

registration: registering your site on providers
authentication: making it possible for clients to login on your site through one or more oauth2 providers
getting remote resources: using access token obtained after client login to retrieve resources owned by client on provider

Please note OAuth2 standards requires your site to be reachable from world wide web, so integration won't be possible on local DEVELOPMENT ENVIRONMENT!

Registration

Your site must first to register itself on vendor's site in order to be able to perform any operation later on. To register your site, following URLs are to be used:

Driver	Url
Facebook	https://developers.facebook.com/
Google	https://console.developers.google.com
LinkedIn	https://www.linkedin.com/developer/apps/new
GitHub	https://github.com/settings/applications/new
VK	https://vk.com/editapp?act=create
Yahoo	https://developer.yahoo.com/apps/create/
Yandex	https://oauth.yandex.com/client/new

Registration results will be typically a combination of:

client id: this is the public key by which site authenticates on vendor, visible to user agent
client secret: this is the public key by which site authenticates on vendor, known only to site and vendor, used to retrieve access token from authorization code.
callback uri: this is location on your site for vendor to redirect authorization codes to

Authentication

Once you had your site registered in one or more providers you need to setup a <oauth2> tag in stdout.xml and feed it with results obtained above. Example:

<oauth2>
    <live>
        <driver name="Facebook" client_id="..." client_secret="..." callback="login/facebook" scopes="..."/>
        <driver name="Google" client_id="..." client_secret="..." callback="login/google" scopes="..."/>
    </live>
</oauth2>

Please note that extra scopes attribute is generally MANDATORY and following values are minimally required for authentication to take place:

Driver	Scopes
Facebook	public_profile, email
Google	https://www.googleapis.com/auth/plus.login, https://www.googleapis.com/auth/plus.profile.emails.read
GitHub	read:user, user:email
LinkedIn	r_basicprofile, r_emailaddress
VK
Yahoo	sdpp-w
Yandex

Each scope identifies an ability client must authorize your site to do on his remote account. For example public_profile & email above allows your site to access client's id, name and email on Facebook if approved. To search for more abilities (scopes) to add, use links below:

Driver	Scopes
Facebook	https://developers.facebook.com/docs/facebook-login/permissions/
Google	https://developers.google.com/identity/protocols/googlescopes
GitHub	https://developer.github.com/v3/
LinkedIn	https://developer.linkedin.com/docs
VK	https://vk.com/dev/methods
Yahoo	https://developer.yahoo.com/oauth2/guide/yahoo_scopes/
Yandex	https://tech.yandex.com/#catalog

Once you finished setting up <oauth2> tag, proceed to configuration and implementation sections in order to start making login by oauth2 providers possible on your site.

Getting Remote Resources

To access any information owned by client on provider site you need to add relevant scope to scopes attribute above (see table above). For example, to get Facebook photos, user_photos scope will be required, so driver becomes:

<driver name="Facebook" scopes="public_profile,email,user_photos" .../>

Once authentication completes and a scope is approved, use getOAuth2Driver method in Lucinda\Project\Attributes class to retrieve remote data based on its resource url. Example for above:
$photos = $this->attributes->getOAuth2Driver()->getResource("https://graph.facebook.com/me/photos");

Handling Errors

Framework wraps any error received from provider (during authentication or resources retrieval) into a Lucinda\OAuth2\Server\Exception, which MUST be automatically handled via a tag <route> @ stderr.xml:

<route id="Lucinda\OAuth2\Server\Exception" error_type="SERVER" status="400" controller="Lucinda\Project\Controllers\OAuth2Error">

Developers then will have to implement Lucinda\Project\Controllers\OAuth2Error in src/Controllers folder. Logic inside differs by project, so framework comes with no default implementation. Example:

namespace Lucinda\Project\Controllers;

use Lucinda\MVC\Response;
use Lucinda\MVC\Response\Redirect;

class OAuth2Error extends Lucinda\STDERR\Controller
{
    public function run(): void
    {
		$redirect = new Redirect("/?oauth2_error=".urlencode($this->request->getException()->getMessage()));
		$redirect->setPermanent(false);
		$redirect->setPreventCaching(true);
		$redirect->run();
    }
}

□ ×