README

Yii Auth

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

Requirements

• PHP 8.1 - 8.5.

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,
        #[\SensitiveParameter] ?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');

HTTP cookie authentication

$authenticationMethod = (new \Yiisoft\Auth\Method\HttpCookie($identityRepository))
    ->withCookieName('access-token');

Typical authentication for websites by storing a token in a browser cookie.

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.

Documentation

• Internals

If you need help or have a question, the Yii Forum is a good place for that. You may also check out other Yii Community Resources.

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.

Support the project

Follow updates