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¶
Authorization header of the HTTP specification
Authorization header of the HTTP specification
Authorization header of the HTTP specification
Array of param-value pairs
Array of authentication instances
Behaviors of the underlying authentication methods
An authentication instance and a matcher callback
Behavior of the underlying authentication method if the matcher callback passes
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¶
use Http\Message\Authentication\QueryParam; $authentication = new QueryParam([ 'access_token' => '9zh987g86fg87gh978hg9g79', ]);
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; > >
© Copyright 2015, The PHP-HTTP Team. Revision 749bb3a1 .
HTTP-аутентификация в PHP
Возможно использовать функцию header() для отправки сообщения «Authentication Required» браузеру, заставив его показать окошко для ввода логина и пароля. Как только пользователь заполнит логин и пароль, ссылка, содержащая PHP-скрипт будет вызвана еще раз с предопределенными переменными PHP_AUTH_USER , PHP_AUTH_PW , и AUTH_TYPE , установленными в логин, пароль и тип аутентификации соответственно. Эти предопределенные переменные хранятся в массивах $_SERVER и $HTTP_SERVER_VARS . Поддерживаются оба типа: «Basic» и «Digest» (начиная с версии PHP 5.1.0). Подробнее смотрите функцию header() .
Замечание: Замечание касательно версии PHP
Суперглобальные переменные, такие как $_SERVER , доступны, начиная с » 4.1.0.
Пример фрагмента скрипта, который вынуждает клиента авторизоваться для просмотра страницы:
Пример #1 Пример Basic HTTP-аутентификации
if (!isset( $_SERVER [ ‘PHP_AUTH_USER’ ])) header ( ‘WWW-Authenticate: Basic realm=»My Realm»‘ );
header ( ‘HTTP/1.0 401 Unauthorized’ );
echo ‘Текст, отправляемый в том случае,
если пользователь нажал кнопку Cancel’ ;
exit;
> else echo «
Hello < $_SERVER [ 'PHP_AUTH_USER' ]>.
» ;
echo «
Вы ввели пароль < $_SERVER [ 'PHP_AUTH_PW' ]>.
» ;
>
?>
Пример #2 Пример Digest HTTP-аутентификации
Это пример реализации простого скрипта Digest HTTP-аутентификации. За подробностями обращайтесь к » RFC 2617.
//user => password
$users = array( ‘admin’ => ‘mypass’ , ‘guest’ => ‘guest’ );
if (empty( $_SERVER [ ‘PHP_AUTH_DIGEST’ ])) header ( ‘HTTP/1.1 401 Unauthorized’ );
header ( ‘WWW-Authenticate: Digest realm color: #007700″>. $realm .
‘»,qop=»auth»,nonce color: #007700″>. uniqid (). ‘»,opaque color: #007700″>. md5 ( $realm ). ‘»‘ );
die( ‘Текст, отправляемый в том случае, если пользователь нажал кнопку Cancel’ );
>
// анализируем переменную PHP_AUTH_DIGEST
if (!( $data = http_digest_parse ( $_SERVER [ ‘PHP_AUTH_DIGEST’ ])) ||
!isset( $users [ $data [ ‘username’ ]]))
die( ‘Неправильные данные!’ );
// генерируем корректный ответ
$A1 = md5 ( $data [ ‘username’ ] . ‘:’ . $realm . ‘:’ . $users [ $data [ ‘username’ ]]);
$A2 = md5 ( $_SERVER [ ‘REQUEST_METHOD’ ]. ‘:’ . $data [ ‘uri’ ]);
$valid_response = md5 ( $A1 . ‘:’ . $data [ ‘nonce’ ]. ‘:’ . $data [ ‘nc’ ]. ‘:’ . $data [ ‘cnonce’ ]. ‘:’ . $data [ ‘qop’ ]. ‘:’ . $A2 );
if ( $data [ ‘response’ ] != $valid_response )
die( ‘Неправильные данные!’ );
// ok, логин и пароль верны
echo ‘Вы вошли как: ‘ . $data [ ‘username’ ];
// функция разбора заголовка http auth
function http_digest_parse ( $txt )
// защита от отсутствующих данных
$needed_parts = array( ‘nonce’ => 1 , ‘nc’ => 1 , ‘cnonce’ => 1 , ‘qop’ => 1 , ‘username’ => 1 , ‘uri’ => 1 , ‘response’ => 1 );
$data = array();
$keys = implode ( ‘|’ , array_keys ( $needed_parts ));
preg_match_all ( ‘@(‘ . $keys . ‘)=(?:([\'»])([^\2]+?)\2|([^\s,]+))@’ , $txt , $matches , PREG_SET_ORDER );
foreach ( $matches as $m ) $data [ $m [ 1 ]] = $m [ 3 ] ? $m [ 3 ] : $m [ 4 ];
unset( $needed_parts [ $m [ 1 ]]);
>
return $needed_parts ? false : $data ;
>
?>
Замечание: Замечание касательно совместимости
Будьте особенно внимательны при указании HTTP-заголовков. Для того, чтобы гарантировать максимальную совместимость с наибольшим количеством различных клиентов, слово «Basic» должно быть написано с большой буквы «B», регион (realm) должен быть взят в двойные (не одинарные!) кавычки, и ровно один пробел должен предшествовать коду 401 в заголовке HTTP/1.0 401. Параметры аутентификации должны разделяться запятыми, как это было показано в примере Digest аутентификации выше.
Вместо простого отображения на экране переменных PHP_AUTH_USER и PHP_AUTH_PW , вам, возможно, понадобится проверить их корректность. Используйте для этого запрос к базе данных или поиск пользователя в dbm-файле.
Вы можете пронаблюдать особенности работы браузера Internet Explorer. Он очень требователен к параметру передаваемых заголовков. Трюк с указанием заголовка WWW-Authenticate перед отправкой статуса HTTP/1.0 401 пока что работает для него.
Для того, чтобы предотвратить написание кем-либо скрипта, раскрывающего пароль к странице, которая использует внешнюю аутентификацию, переменные PHP_AUTH не устанавливаются в случае, если данная страница использует внешнюю аутентификацию и установлен безопасный режим. Несмотря на это, переменная REMOTE_USER может использоваться для аутентификации пользователя, прошедшего внешнюю аутентификацию. Таким образом, вы всегда можете воспользоваться переменной $_SERVER[‘REMOTE_USER’] .
Замечание: Замечание касательно конфигурации
PHP использует указание директивы AuthType для указания того, используется внешняя аутентификация или нет.
Следует заметить, что все вышесказанное не предотвращает похищения паролей к страницам, требующим авторизацию, кем-либо, кто контролирует страницы без авторизации, расположенные на том же сервере.
И Netscape Navigator и Internet Explorer очищают кэш аутентификации текущего окна для заданного региона (realm) при получении от сервера статуса 401. Это может использоваться для реализации принудительного выхода пользователя и повторного отображения диалогового окна для ввода имени пользователя и пароля. Некоторые разработчики используют это для ограничения авторизации по времени или для предоставления кнопки «Выход».
Пример #3 Пример HTTP-аутентификации с принудительным вводом новой пары логин/пароль
function authenticate () header ( ‘WWW-Authenticate: Basic realm=»Test Authentication System»‘ );
header ( ‘HTTP/1.0 401 Unauthorized’ );
echo «Вы должны ввести корректный логин и пароль для получения доступа к ресурсу \n» ;
exit;
>
Это поведение не регламентируется стандартами HTTP Basic-аутентификации, следовательно, вы не должны зависеть от этого. Тестирование браузера Lynx показало, что Lynx не очищает кэш авторизации при получении от сервера статуса 401, и, нажав последовательно «Back», а затем «Forward» возможно открыть такую страницу, при условии, что требуемые атрибуты авторизации не изменились. Однако, пользователь может нажать клавишу ‘_’ для очистки кеша аутентификации.
Для того, чтобы добиться корректной работы HTTP-аутентификации в IIS сервере с CGI версией PHP, вы должны отредактировать конфигурационную настройку IIS под названием «Directory Security«. Щелкните на надписи «Edit» и установите опцию «Anonymous Access«, все остальные поля должны остаться неотмеченными.
Замечание: Замечание касательно IIS:
Для того, чтобы HTTP-аутентификация корректно работала в IIS, в конфигурации PHP опция cgi.rfc2616_headers должна быть установлена значением 0 (значение по умолчанию).
Замечание:
В случае, если используется безопасный режим, UID текущего скрипта будет добавлен в realm-часть заголовка WWW-Authenticate.