Framework Skeleton: OAuth2 Integration

OAuth2 integration is performed automatically by this framework through an interplay of no less than four independent APIs as well as developer himself, each with their own responsibilities:

  1. developers: responsible in setting up credentials for each OAuth2 provider following site registration in stdout.xml
  2. OAuth2 Client API: responsible in communicating with OAuth2 providers
  3. Web Security API: responsible in holding generic recipe for authentication using OAuth2 providers
  4. Framework Skeleton API: responsible in storing drivers developed on Framework Engine API blueprints that bind between the two APIs above in order to authenticate on each OAuth2 provider
  5. Framework Engine API: responsible in binding Web Security API recipe to OAuth2 Client API implementation using drivers set up by Framework Skeleton API and credentials set by developers

Steps #2, #3, #5 require no developer intervention, so let us detail the other two into the following required steps relevant for developers:

  1. registering site on oauth2 provider
  2. saving site credentials obtained
  3. setting up login routes
  4. choosing scopes
  5. configuring drivers

To make integration possible, SecurityListener MUST be activated and <security> tag MUST be set up properly (see below).

Registering site on OAuth2 provider

For each provider your site needs to authenticate with (eg: Facebook) and retrieve resources from (eg: friends) you MUST register your site on provider site in order to obtain credentials, as described here. You will need to do so for each development environment (eg: dev, live), because value of redirect uri credential will need to change accordingly!

NOTE: Value of redirect uri should always point to /login/LOWERCASE_PROVIDER_NAME route on your site (eg:!

Saving site credentials obtained

Once site is registered on provider, crendentials (client id , client secret and redirect uri) obtained MUST be saved in a <driver> tag, child of development environment, child of <oauth2> @ stdout.xml. Each vendor your app supports must correspond to a <driver> tag! Example:

<oauth2 dao="Users"> <live> <driver name="Facebook" client_id="APP_ID_LIVE" client_secret="APP_SECRET_LIVE" callback="login/facebook"/> <driver name="Google" client_id="APP_ID_LIVE" client_secret="APP_SECRET_LIVE" callback="login/google"/> </live> <dev> <driver name="Facebook" client_id="APP_ID_DEV" client_secret="APP_SECRET_DEV" callback="login/facebook"/> <driver name="Google" client_id="APP_ID_DEV" client_secret="APP_SECRET_DEV" callback="login/google"/> </dev> </oauth2>

Setting up login routes

Now that you have saved credentials, to allow login on provider you also need to open stdout.xml and set all routes referenced by callbacks. Example:

<routes> ... <route url="login/facebook"/> <route url="login/google"/> </route>

Choosing scopes

OAuth2 standard requires providers to associate resources they are serving with one or more SCOPES (go here for documentation about scopes they offer) . By default, when framework is installed, only scopes required for retrieving logged in user info are requested for approval (see drivers section below!).

To add more scopes (more abilities), you need to populate scopes attribute of matching <driver> @ <oauth2> tag with list of scopes separated by commas. Example (tells Facebook you want to access user's photos as well):

<driver name="Facebook" client_id="APP_ID_LIVE" client_secret="APP_SECRET_LIVE" callback="login/facebook" scopes="user_photos">

Once scopes are defined there, they will be merged with default ones already required for authentication.

Configuring drivers

As stated above, skeleton comes with drivers already implemented developed on Framework Engine API blueprints that bind between Web Security API and OAuth2 Client API above in order to authenticate users on OAuth2 providers. In order to make that possible each driver comes with:

Following classes are implemented on skeleton to accomodate this need:

All of above classes are found in application/models/oauth2 folder and they are configurable by: