Tutorials: Integrating OAuth2 Providers

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:

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


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:


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

<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
Yahoo sdpp-w

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 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 getRemoteResource function to retrieve remote data based on its resource url. Example for above:

Handling Errors

Framework wraps any error received from provider (during authentication or resources retrieval) into a , which MUST be automatically handled via a tag @ stderr.xml:

<exception class="" error_type="SERVER" status="400" controller="OAuth2ErrorController">

Developers MUST implement OAuth2ErrorController in application/controllers folder. Logic inside differs by project, so framework comes with no default implementation. Example:

class OAuth2ErrorController extends { public function run(): void { Request::redirect("/?oauth2_error=".urlencode($this->request->getException()->getMessage()), false, true); } }