Authentication
The Authentication component allows you to to implement authentication methods which can simply update the request
with authentication detail (for example by adding an Authorization
header).
This is useful when you have to send multiple requests to the same endpoint. Using an authentication implementation,
these details can be separated from the actual requests.
Installation
$ composer require php-http/message
Authentication Methods
Method |
Parameters |
Behavior |
---|---|---|
Username and password |
|
|
Bearer |
Token |
|
Username and password |
|
|
Query Params |
Array of param-value pairs |
URI parameters |
Chain |
Array of authentication instances |
Behaviors of the underlying authentication methods |
Matching |
An authentication instance and a matcher callback |
Behavior of the underlying authentication method if the matcher callback passes |
Header |
Header name and value |
Add an arbitrary authentication header |
Integration with HTTPlug
Normally requests must be authenticated “by hand” which is not really convenient.
If you use HTTPlug, you can integrate this component into the client using the authentication plugin.
Examples
General usage looks like the following:
$authentication = new AuthenticationMethod();
/** @var Psr\Http\Message\RequestInterface */
$authentication->authenticate($request);
Basic Auth
use Http\Message\Authentication\BasicAuth;
$authentication = new BasicAuth('username', 'password');
Bearer
use Http\Message\Authentication\Bearer;
$authentication = new Bearer('token');
WSSE
use Http\Message\Authentication\Wsse;
$authentication = new Wsse('username', 'password');
For better security, also pass the 3rd optional parameter to use a better hashing algorithm than sha1
, e.g.
use Http\Message\Authentication\Wsse;
$authentication = new Wsse('username', 'password', 'sha512');
Query Params
http://api.example.com/endpoint?access_token=9zh987g86fg87gh978hg9g79
:
use Http\Message\Authentication\QueryParam;
$authentication = new QueryParam([
'access_token' => '9zh987g86fg87gh978hg9g79',
]);
Warning
Using query parameters for authentication is not safe. Only use it when this is the only authentication method offered by a third party application.
Chain
The idea behind this authentication method is that in some cases you might need to authenticate the request with multiple methods.
For example it’s a common practice to protect development APIs with Basic Auth and the regular token authentication as well to protect the API from unnecessary processing:
use Http\Message\Authentication\Chain;
$authenticationChain = [
new AuthenticationMethod1(),
new AuthenticationMethod2(),
];
$authentication = new Chain($authenticationChain);
Matching
With this authentication method you can conditionally add authentication details to your request by passing a callable to it. When a request is passed, the callable is called and used as a boolean value in order to decide whether the request should be authenticated or not. It also accepts an authentication method instance which does the actual authentication when the condition is fulfilled.
For example a common use case is to authenticate requests sent to certain paths:
use Http\Message\Authentication\Matching;
use Psr\Http\Message\RequestInterface;
$authentication = new Matching(
new AuthenticationMethod1(),
function (RequestInterface $request) {
$path = $request->getUri()->getPath();
return 0 === strpos($path, '/api');
}
);
In order to ease creating matchers for URLs/paths, there is a static factory method for this purpose: createUrlMatcher
The first argument is an authentication method, the second is a regular expression to match against the URL:
use Http\Message\Authentication\Matching;
$authentication = Matching::createUrlMatcher(new AuthenticationMethod(), '\/api');
Header
With this authentication method you can add arbitrary headers.
In the following example, we are setting a X-AUTH-TOKEN
header with it’s value:
use Http\Message\Authentication\Header;
$authentication = new Header('X-AUTH-TOKEN', '9zh987g86fg87gh978hg9g79');
Implement Your Own
Implementing an authentication method is easy: only one method needs to be implemented:
use Http\Message\Authentication;
use Psr\Http\Message\RequestInterface;
class MyAuth implements Authentication
{
public function authenticate(RequestInterface $request)
{
// do something with the request
// keep in mind that the request is immutable - return the updated
// version of the request with the authentication information added
// to it.
return $request;
}
}