yiisoft/auth

Yii auth

3.0.1 2021-02-10 21:44 UTC

README

68747470733a2f2f796969736f66742e6769746875622e696f2f646f63732f696d616765732f7969695f6c6f676f2e737667

Yii Auth


Latest Stable Version Total Downloads Build status Scrutinizer Code Quality Code Coverage Mutation testing badge static analysis type-coverage

The package provides various authentication methods, a set of abstractions to implement in your application, and a PSR-15 middleware to authenticate an identity.

Installation

composer require yiisoft/auth

General usage

Configure a middleware and add it to your middleware stack:

$identityRepository = getIdentityWithTokenRepository(); // \Yiisoft\Auth\IdentityRepositoryInterface
$authenticationMethod = new \Yiisoft\Auth\Method\HttpBasic($identityRepository);

$middleware = new \Yiisoft\Auth\Middleware\Authentication(
    $authenticationMethod,
    $responseFactory, // PSR-17 ResponseFactoryInterface
    $failureHandler // optional, \Yiisoft\Auth\Handler\AuthenticationFailureHandler by default
);

$middlewareDispatcher->addMiddleware($middleware);

In order to get an identity instance in the following middleware use getAttribute() method of the request instance:

public function actionIndex(\Psr\Http\Message\ServerRequestInterface $request): \Psr\Http\Message\ResponseInterface
{
    $identity = $request->getAttribute(\Yiisoft\Auth\Middleware\Authentication::class);
    // ...
}

HTTP basic authentication

Basic HTTP authentication is typically used for entering login and password in the browser. Credentials are passed as $_SERVER['PHP_AUTH_USER'] and $_SERVER['PHP_AUTH_PW'].

$authenticationMethod = (new \Yiisoft\Auth\Method\HttpBasic($identityRepository))
    ->withRealm('Admin')
    ->withAuthenticationCallback(static function (
        ?string $username,
        ?string $password,
        \Yiisoft\Auth\IdentityWithTokenRepositoryInterface $identityRepository
    ): ?\Yiisoft\Auth\IdentityInterface {
        return $identityRepository->findIdentityByToken($username, \Yiisoft\Auth\Method\HttpBasic::class);
    });

Realm is typically what you will see in the browser prompt asking for a login and a password. Custom authentication callback set in the above is the same as default behavior when it is not specified.

HTTP bearer authentication

Bearer HTTP authentication is typically used in APIs. Authentication token is passed in WWW-Authenticate header.

$authenticationMethod = new \Yiisoft\Auth\Method\HttpBearer($identityRepository);

Custom HTTP header authentication

Custom HTTP header could be used if you do not want to leverage bearer token authentication:

 $authenticationMethod = (new \Yiisoft\Auth\Method\HttpHeader($identityRepository))
     ->withHeaderName('X-Api-Key')
     ->withPattern('/(.*)/'); // default

In the above we use full value of X-Api-Key header as token.

Query parameter authentication

This authentication method is mainly used by clients unable to send headers. In case you do not have such clients we advise not to use it.

$authenticationMethod = (new \Yiisoft\Auth\Method\QueryParameter($identityRepository))
    ->withParameterName('token');

Using multiple authentication methods

To use multiple authentication methods, use Yiisoft\Auth\Method\Composite:

$authenticationMethod = new \Yiisoft\Auth\Method\Composite([
    $bearerAuthenticationMethod,
    $basicAuthenticationMethod
]);

Extension and integration points

  • \Yiisoft\Auth\IdentityInterface should be implemented by your application identity class. Typically, that is User.
  • \Yiisoft\Auth\IdentityRepositoryInterface should be implemented by your application identity repository class. Typically, that is UserIdentity.
  • \Yiisoft\Auth\IdentityWithTokenRepositoryInterface could be additionally implemented by your application identity repository class in case token-based authentication is needed. Typically, that is UserIdentity.
  • \Yiisoft\Auth\AuthenticationMethodInterface could be implemented to provide your own authentication method.

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework. To run it:

./vendor/bin/infection

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

Support the project

Open Collective

Follow updates

Official website Twitter Telegram Facebook Slack

License

The Yii Auth is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.