README

A PHP7.2+ OAuth1/2 client with an integrated API wrapper, loosely based on Lusitanian/PHPoAuthLib.

Documentation

Requirements

• PHP 7.2+
• a PSR-18 compatible HTTP client library of your choice (there is one included, though)
  • optional PSR-17 compatible Request-, Response- and UriFactories
• see chillerlan/php-oauth-providers for already implemented providers

Installation

requires composer

composer.json (note: replace dev-master with a version boundary)

{
	"require": {
		"php": "^7.2",
		"chillerlan/php-oauth-core": "dev-master"
	}
}

Profit!

API

OAuthInterface

The OAuthInterface implements the PSR-18 ClientInterface (a PSR-18 compatible http client is still required), the PSR-3LoggerAwareInterface as well as the ApiClientInterface and offers basic methods that are common to the OAuth 1/2 interfaces, all supplied in the abstract class OAuthProvider.

The following public properties are available:

The following internal (protected) properties affect a provider's functionality

OAuth1Interface

Protected properties:

A minimal OAuth1 provider

use chillerlan\OAuth\Core\OAuth1Provider;

class MyOauth1Provider extends Oauth1Provider{

	protected $requestTokenURL = 'https://example.com/oauth/request_token';
	protected $authURL         = 'https://example.com/oauth/authorize';
	protected $accessTokenURL  = 'https://example.com/oauth/access_token';
	protected $apiURL          = 'https://api.example.com';

}

OAuth2Interface

Protected properties:

ClientCredentials

The ClientCredentials interface indicates that the provider supports the client credentials grant type.

CSRFToken

The CSRFToken interface enables usage of the <state> parameter to mitigate cross-site request forgery and automatically enforces it during authorization requests.

TokenRefresh

The TokenRefresh interface indicates if a provider supports usage of refresh tokens. The option setting $tokenAutoRefresh enables automatic refresh of expired tokens when using the OAuthInterface::request() or the PSR-18 OAuthInterface::sendRequest() methods to call the provider's API.

A minimal OAuth2 provider

use chillerlan\OAuth\Core\OAuth2Provider;

class MyOauth2Provider extends Oauth2Provider implements ClientCredentials, CSRFToken, TokenRefresh{

	protected $authURL                   = 'https://example.com/oauth2/authorize';
	protected $accessTokenURL            = 'https://example.com/oauth2/token';
	protected $apiURL                    = 'https://api.example.com';

	// optional
	protected $clientCredentialsTokenURL = 'https://example.com/oauth2/client_credentials';
	protected $authMethod                = self::AUTH_METHOD_HEADER;
	protected $authMethodHeader          = 'OAuth';
	protected $scopesDelimiter           = ',';
}

OAuthStorageInterface

The OAuthStorageInterface serves for storing access tokens and auth states (CSRF) on a per-user basis. The included implementations are intended for throwaway use during authentication or script runtime, please refer to these for implementation details (extend OAuthStorageAbstract):

• MemoryStorage: non-persistent, to store an existing token during script runtime and then discard it.
• SessionStorage: (half-)persistent, stores a token for as long a user's session is alive, e.g. while authenticating.

An example implementation for a persistent database storage with token encryption can be found over here: DBStorage.

AccessToken

The AccessToken is a container to keep any token related data in one place. It extends the SettingsContainerInterface and therefore offers all of its methods.

inherited from SettingsContainerInterface:

OAuthOptions

OAuthOptions is a SettingsContainerInterface that uses the plug-in traits OAuthOptionsTrait and HTTPOptionsTrait to provide settings for a provider.

from HTTPOptionsTrait:

Testing

If you just wrote your own provider implementation, you also might want to test it. This library brings several abstract tests that you can use. In order to use them, you need to add the PSR-4 namespaces to your project's composer.json like so:

{
	...

	"autoload": {
		"psr-4": {
			"my\\project\\source\\": "src/"
		}
	},
	"autoload-dev": {
		"psr-4": {
			"my\\project\\test\\": "tests/",

			...

			"chillerlan\\HTTPTest\\MagicAPI\\": "vendor/chillerlan/php-magic-apiclient/tests",
			"chillerlan\\OAuthTest\\": "vendor/chillerlan/php-oauth-core/tests"
		}
	}
}

The basic unit test looks as follows:

namespace my\project\test;

use my\project\source\MyProvider;
use chillerlan\OAuthTest\Providers\OAuth2ProviderTestAbstract;

/**
 * @property \my\project\source\MyProvider $provider
 */
class MyProviderTest extends OAuth2ProviderTestAbstract{

	protected $CFG = __DIR__.'/../config'; // specifies the path for .env, cacert.pem and oauth tokens
	protected $FQN = MyProvider::class;

}

That is all! You'll only need to add/overload methods in case you need to cover edge cases or additional features of your provider implementation.

In case you want to run tests against a live API, you can use the abstract API tests. The live API tests are disabled on (Travis) CI and you need to enable them explicit by changing the line IS_CI=TRUE in you project's .env.

namespace my\project\test;

use my\project\source\MyProvider;
use chillerlan\OAuthTest\Providers\OAuth2APITestAbstract;

/**
 * @property \my\project\source\MyProvider $provider
 */
class MyProviderAPITest extends OAuth2APITestAbstract{

	protected $CFG = __DIR__.'/../config';
	protected $FQN = MyProvider::class;
	protected $ENV = 'MYPROVIDER'; // the prefix for the provider's name in .env

	// your live API tests here
	public function testIdentity(){
		$r = $this->provider->identity();
		$this->assertSame($this->testuser, $this->responseJson($r)->id);
	}

}

Disclaimer

OAuth tokens are secrets and should be treated as such. Store them in a safe place, consider encryption.
I won't take responsibility for stolen auth tokens. Use at your own risk.