README.md

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.