chillerlan/php-oauth

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

1.0.1 2024-05-30 16:10 UTC

Requires

• php: ^8.1
• ext-json: *
• ext-sodium: *
• chillerlan/php-http-message-utils: ^2.2.1
• chillerlan/php-settings-container: ^3.2
• psr/http-client: ^1.0
• psr/http-message: ^1.1 || ^2.0
• psr/log: ^1.1 || ^2.0 || ^3.0

Requires (Dev)

• chillerlan/php-dotenv: ^3.0
• chillerlan/phpunit-http: ^1.0
• guzzlehttp/guzzle: ^7.8
• monolog/monolog: ^3.6
• phan/phan: ^5.4
• phpmd/phpmd: ^2.15
• phpunit/phpunit: ^10.5
• squizlabs/php_codesniffer: ^3.9

Suggests

• chillerlan/php-httpinterface: ^6.0 - an alternative PSR-18 HTTP Client

Provides

• psr/http-client-implementation: 1.0

MIT

• smiley

• authorization
• Authentication
• client
• oauth
• oauth2
• oauth1
• rfc6749
• psr-7
• psr-17
• psr-18
• rfc5849
• pkce
• rfc7636

README

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

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.