PHP OAuth2 Integration Explained

Early in the history of web applications came a necessity of authorizing access to resources not meant to be public. Up until the advent of OAuth in 2006, virtually all web applications were owners of resources they offered, which means authorization process was internal to every app. Then came a simple idea: what if more than one app wants to share a single authorization process from a remote account (eg: site X, Y, Z want to forward authorization to Facebook, so they won't need to implement their own) and what if an app wants to have access to remote account resources owned by user instead? These two basic requirements, impossible with standard authorization, paved the way for OAuth.

What is OAuth2 and how does it work?

Oauth is a protocol that defines the ways a CLIENT app can access resources owned by USER on SERVER app and OAuth2 is its improved version that forms a worldwide industry standard today. For this whole process to work, each part (client & server) has to follow IETF specifications.

Three actors take part in OAuth2 communication logic:

What is an access token?

Protocol specifies multiple venues of communication between CLIENT and SERVER. Regardless of venue, in order to request a RESOURCE, CLIENT needs to hold a long lived ACCESS TOKEN. Sending that ACCESS TOKEN, it authenticates itself on SERVER for every RESOURCE request. This token is created by SERVER once USER has approved GRANTS associated to that RESOURCE and any other CLIENT wants on USER's SERVER account. A GRANT or SCOPE is an access right associated to one or more RESOURCE. For example there is a GRANT for seeing USER's basic profile info and another for seeing USER's friends. In order to be able to see both, CLIENT needs USER to approve both grants.

OAuth2 standard defines many GRANT TYPES, but AUTHORIZATION CODE is the only that should be used in most web applications because it keeps ACCESS TOKEN obtained following grant's approval hidden from outside world, known only to the application that requested them.

What is a scope?

OAuth2 specification associates each resource owned on provider by your site user to a SCOPE. Scope can be understood as an access right to a resource or a group of related resources. Each scope (access level) needs to be explicitly approved by your site user. Once approved, using authorization code provider sends, your site automatically requests an access token. Using this long-lived token, application authenticates itself in every resource request on vendor site.

How to register your CLIENT on SERVER site?

For any operation to perform on OAUTH2 SERVER, CLIENT APP needs first to register itself on former site in order to obtain credentials. Typically these are:

Once obtained, these credentials will be used whenever it is required to obtain an ACCESS TOKEN.

How is ACCESS TOKEN obtained using authorization code GRANT TYPE?

Once CLIENT has registered, it is able to obtain ACCESS TOKEN:

How is ACCESS TOKEN used by CLIENT to retrieve RESOURCE?

Once an ACCESS TOKEN was obtained, CLIENT is finally able to ask for RESOURCE:

PHP OAuth2 Integration

As one can see by reading docs, the protocol itself is quite complicated as it involves both SERVER and CLIENT implementations, but relevant for PHP developers are only its CLIENT side. Seldom if ever are OAuth2 SERVERs developed in PHP, due to their high throughput and traffic demands.

Each OAuth2 SERVER (or provider) implements IETF specifications referenced above and offers an official PHP driver for developers to use in building an OAuth2 CLIENT that connects to it. The problem of using it is that most of logic inside is dictated by IETF specifications, so common to all CLIENT drivers.

OAuth2 Client API, part of Lucinda Framework, abstracts all CLIENT logic based on IETF specifications, while Lucinda Framework binds that logic to actual vendor implementations (eg: Facebook). Together, they allow developers to setup an OAuth2 CLIENT just with a few changes in XML only!