chillerlan / php-oauth Goto Github PK

A fully transparent, framework agnostic PSR-18 OAuth client.

License: MIT License

Twig 0.09% PHP 99.91%

oauth oauth-client oauth1 oauth1-client oauth2 oauth2-client php php8 psr-18 psr-7

php-oauth's Introduction

chillerlan/php-oauth

A transparent, framework-agnostic, easily extensible PHP PSR-18 OAuth client with a user-friendly API, fully PSR-7/PSR-17 compatible.

Overview

Features

OAuth client capabilities
- OAuth 1.0a (RFC-5849)
- OAuth 2.0 (RFC-6749)
  - Authorization Code Grant
  - Client Credentials Grant
  - Token refresh
  - CSRF Token ("state" parameter)
  - RFC-7009: Token Revocation
  - RFC-7636: PKCE (Proof Key for Code Exchange)
  - RFC-9126: PAR (Pushed Authorization Requests)
  - ~~RFC-9449: DPoP (Demonstrating Proof of Possession)~~ (planned)
- Proprietary, OAuth-like authorization flows (e.g. Last.fm)
- Invalidation of access tokens (if supported by the provider)
Several built-in provider implementations (see below)
- Provider instances act as PSR-18 HTTP client, wrapping the given PSR-18 HTTP instance
- Requests to the provider API will have required OAuth headers and tokens added automatically
Optional token encryption via sodium_crypto_secretbox() for the internal storage engines
A unified user data object AuthenticatedUser via the OAuthInterface::me() method

Requirements

PHP 8.1+
- extensions: json, sodium
  - from dependencies: curl, fileinfo, intl, mbstring, simplexml, zlib
a PSR-18 compatible HTTP client library of your choice
PSR-17 compatible RequestFactory, StreamFactory and UriFactory

Documentation

The user manual is at https://php-oauth.readthedocs.io/ (sources)
An API documentation created with phpDocumentor can be found at https://chillerlan.github.io/php-oauth/
The documentation for the AccessToken, AuthenticatedUser and OAuthOptions containers can be found here: chillerlan/php-settings-container
There is the suite of get-token examples, which is mostly intended for development, and there are self-contained examples for a quickstart:
- OAuth1 example
- OAuth2 example

Installation with composer

See the installation guide for more info!

Terminal

composer require chillerlan/php-oauth

composer.json

{
	"require": {
		"php": "^8.1",
		"chillerlan/php-oauth": "^1.0"
	}
}

Note: check the releases for valid versions.

Implemented Providers

Provider	keys	revoke	ver	User	CSRF	PKCE	CC	TR	TI
Amazon	link		2	✓	✓			✓
BattleNet	link	link	2	✓	✓		✓
BigCartel	link	link	2	✓	✓				✓
Bitbucket	link		2	✓	✓		✓	✓
Codeberg	link	link	2	✓	✓	✓		✓
Deezer	link	link	2	✓	✓
DeviantArt	link	link	2	✓	✓		✓	✓	✓
Discogs	link	link	1	✓
Discord	link		2	✓	✓		✓	✓	✓
Flickr	link	link	1	✓
Foursquare	link	link	2	✓
Gitea	link	link	2	✓	✓	✓		✓
GitHub	link	link	2	✓	✓			✓
GitLab	link		2	✓	✓		✓	✓
Google	link	link	2	✓	✓
GuildWars2	link	link	2	✓
Imgur	link	link	2	✓	✓			✓
LastFM	link	link	-	✓
MailChimp	link		2	✓	✓
Mastodon	link	link	2	✓	✓			✓
MicrosoftGraph	link	link	2	✓	✓
Mixcloud	link	link	2	✓
MusicBrainz	link	link	2	✓	✓			✓	✓
NPROne	link		2	✓	✓			✓	✓
OpenCaching	link	link	1	✓
OpenStreetmap	link		1	✓
OpenStreetmap2	link		2	✓	✓
Patreon	link		2	✓	✓			✓
PayPal	link		2	✓	✓		✓	✓
PayPalSandbox	link		2	✓	✓		✓	✓
Pinterest	link	link	2	✓	✓			✓
Reddit	link	link	2	✓	✓		✓	✓	✓
Slack	link	link	2	✓	✓
SoundCloud	link	link	2	✓			✓	✓
Spotify	link	link	2	✓	✓		✓	✓
Steam	link		-	✓
Stripe	link	link	2	✓	✓			✓	✓
Tumblr	link	link	1	✓
Tumblr2	link	link	2	✓	✓		✓	✓
Twitch	link	link	2	✓	✓		✓	✓	✓
Twitter	link	link	1	✓
TwitterCC	link	link	2				✓
Vimeo	link	link	2	✓	✓		✓		✓
WordPress	link	link	2	✓	✓
YouTube	link	link	2	✓	✓

Legend:

Provider: the name of the provider class and link to their API documentation
keys: links to the provider's OAuth application creation page
revoke: links to the OAuth application access revocation page in the provider's user profile
ver: the OAuth version(s) supported by the provider
User: indicates that the provider offers information about the currently authenticated user via the me() method (implements the UserInfo interface)
CSRF: indicates that the provider uses CSRF protection via the state parameter (implements the CSRFToken interface)
PKCE: indicates that the provider supports Proof Key for Code Exchange (implements the PKCE interface)
CC: indicates that the provider supports the Client Credentials Grant (implements the ClientCredentials interface)
TR: indicates that the provider is capable of refreshing an access token (implements the TokenRefresh interface)
TI: indicates that the provider is capable of revoking/invalidating an access token (implements the TokenInvalidate interface)

Disclaimer

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

Privacy policy

This library does not store or process user data on its own - it only handles the OAuth flow for an application.
Implementers are responsible for a proper privacy policy in accordance with the service providers.

php-oauth's People

Contributors

Stargazers

Watchers

php-oauth's Issues

[ENHANCEMENT] RFC-9449 OAuth 2.0 Demonstrating Proof of Possession (DPoP)

Describe the feature

The feature is documented in RFC-9449.

Right now I don't see the need to implement abstract support for this, as there are currently no major services out in the wild that support it (as it is a relatively new proposal).
Further, the underlying protocol has a lot of dependencies (RFCs 7515, 7516, 7517, 7518, 7519, 7520, 7521, 7523) that translate into one or more additional libraries, such as firebase/php-jwt or web-token/jwt-framework for example, which is not justifiable at this point.
Bluesky's upcoming OAuth2 support might be the first implementation that makes use of it, and once it is rolled out, I'll figure out implementation details and whether to depend on external libraries or just roll a minimum JWT implementation for this specific provider.

Code sample (if applicable)

DPoP introduces the concept of a DPoP proof, which is a JWT created by the client and sent with an HTTP request using the DPoP header field. Each HTTP request requires a unique DPoP proof.

The DPoP proof is sent with the access token request, hence it should be created once the authorization code is received, so in OAuth2Provider::getAccessToken(). Ideal is probably OAuth2Provider::sendAccessTokenRequest() which is called in the aforementioned method and which has direct access to the PSR-7 RequestInterface instance:

	protected function sendAccessTokenRequest(string $url, array $body):ResponseInterface{

		$request = $this->requestFactory
			->createRequest('POST', $url)
			->withHeader('Accept', 'application/json')
			->withHeader('Accept-Encoding', 'identity')
			->withHeader('Content-Type', 'application/x-www-form-urlencoded')
			->withBody($this->streamFactory->createStream(QueryUtil::build($body, PHP_QUERY_RFC1738)))
		;

		foreach($this::HEADERS_AUTH as $header => $value){
			$request = $request->withHeader($header, $value);
		}

		if($this::USES_BASIC_AUTH_IN_ACCESS_TOKEN_REQUEST){
			$request = $this->addBasicAuthHeader($request);
		}

		// as with all additional features, an interface will be added
		if($this instanceof DPoP){
			$dpopProof = $this->createDpopProof(/* ... */);

			$request = $request->withHeader('DPoP', $dpopProof);
		}

		return $this->http->sendRequest($request);
	}

During creation of the proof, the generated private key should be saved for the current user, which requires additional methods in the storage interface as the key is required for subsequent proofs:

OAuthStorageInterface::storeDpopPrivateKey(string $key, string $provider):static
[get, has, clear, clearAll...]

No changes are required to the token response parser or the AccessToken class as the only difference here is that the access token is a JWT that contains data instead of a random string.

The request authorization boils down to:

	public function getRequestAuthorization(RequestInterface $request, AccessToken|null $token = null):RequestInterface{
		$token ??= $this->storage->getAccessToken($this->name);

		if($token->isExpired()){

			if(!$this instanceof TokenRefresh || $this->options->tokenAutoRefresh !== true){
				throw new InvalidAccessTokenException;
			}

			$token = $this->refreshAccessToken($token);
		}

		return $request
			// the "Bearer" changes to "DPoP" as per spec (or whatever the service doc says)
			->withHeader('Authorization', 'DPoP '.$token->accessToken)
			// additionally, a DPoP proof is attached
			->withHeader('DPoP', $this->createDpopProof(/* ... */))
		;
	}

Are you (the requester) willing to submit a pull request for that feature?

[YES] (I guess I'll have to!?)

[Provider] Garmin: oauth_verifier in params in getRequestAuthorization

To get the User Access Token from Garmin Connect Api, I've used the public method getAccessToken in OAuth1Provider.php. In the public method getRequestAuthorization I've added oauth_verifier in the params:

public function getRequestAuthorization(RequestInterface $request, AccessToken|null $token = null):RequestInterface{
		$token ??= $this->storage->getAccessToken($this->name);

		if($token->isExpired()){
			throw new InvalidAccessTokenException;
		}

		$params = [
			'oauth_consumer_key'     => $this->options->key,
			'oauth_nonce'            => $this->nonce(),
			'oauth_signature_method' => 'HMAC-SHA1',
			'oauth_timestamp'        => time(),
			'oauth_token'            => $token->accessToken,
			'oauth_version'          => '1.0',
                        'oauth_verifier'          => $verifier,
		];

		$params['oauth_signature'] = $this->getSignature(
			$request->getUri(),
			$params,
			$request->getMethod(),
			$token->accessTokenSecret,
		);

		return $request->withHeader('Authorization', sprintf('OAuth %s', QueryUtil::build($params, null, ', ', '"')));
}

Because without oauth_verifier I got an error in the response from Guzzle.