mle86 / request-authentication
A simple library for API request authentication.
Requires
- php: >=7.1
- paragonie/halite: ^4.4||^3.4
- psr/http-message: ^1.0
- psr/http-server-middleware: ^1.0
- whitehat101/apr1-md5: ^1.0
Requires (Dev)
- guzzlehttp/guzzle: ^6.3
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^7
- psr/simple-cache: ^1.0
- roave/security-advisories: dev-master
- symfony/http-foundation: ^4.0
Suggests
- guzzlehttp/guzzle: The library can be used as a GuzzleHttp middleware.
- symfony/http-foundation: The library can process HttpFoundation's Request and Response interfaces.
README
This PHP library provides a generic interface for authenticating outbound API requests and for verifying inbound API requests' authentication.
It is released under the MIT License.
Installation
Via Composer: $ composer require mle86/request-authentication
Or insert this into your project's composer.json file:
"require": { "mle86/request-authentication": "^0" }
Dependencies and Minimum PHP Version
-
PHP 7.1
-
The PSR-7 interfaces (psr/http-message)
-
The PSR-15 interfaces (psr/http-server-middleware)
-
The whitehat101/apr1-md5 package for
$apr1$hash support in BasicHashAuthenticationMethod -
The paragonie/halite package for the PublicKeyMethod class
Workflow
This library contains several AuthenticationMethod classes.
Each of those represents one mechanism for request authentication and verification.
The BasicAuthenticationMethod for example adds an Authorization: Basic … HTTP header to outbound requests
and verifies that header in inbound requests against a list of known usernames and their passwords.
Usually the AuthenticationMethod classes won't be used directly (apart from instantiating them), there's the RequestAuthenticator and RequestVerifier wrapper classes instead that take an AuthenticationMethod dependency.
To sign/authenticate an outbound request
you'll need an AuthenticationMethod instance
wrapped in a RequestAuthenticator instance,
a client ID and a client secret,
and the request to sign.
The authenticate() method will add
the required authentication headers
to the request
so that it can be sent.
To verify an inbound request
you'll need an AuthenticationMethod instance of the same class
wrapped in a RequestVerifier instance
and a KeyRepository that will map the request's client ID
to the same client secret used for signing the request.
(In case of the PublicKeyMethod class,
the client will use its private key for signing
and the KeyRepository must return the client's public key.)
Classes and Interfaces
- Main wrapper classes:
- RequestAuthenticator wrapper class,
- RequestVerifier wrapper class.
- AuthenticationMethod main interface:
- BasicAuthenticationMethod class,
- BasicHashAuthenticationMethod class,
- DefaultAuthenticationMethod class,
- PublicKeyMethod class,
- MethodStack composite class.
- RequestInfo data transfer object.
- KeyRepository base class:
- FileRepository class,
- ArrayRepository class.
- RequestIdList interface:
- CacheRequestIdList class.
- Exception classes.