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:
Steps #2, #3, #5 require no developer intervention, so let us detail the other two into the following required steps relevant for developers:
To make integration possible, SecurityListener MUST be activated and <security> tag MUST be set up properly (see below).
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: https://www.example.com/login/facebook)!
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>
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>
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.
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: