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

Basic Auth

Username and password

Authorization header of the HTTP specification

Bearer

Token

Authorization header of the HTTP specification

WSSE

Username and password

Authorization header of the HTTP specification

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');

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;
    }
}