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

• PHP 8.0 or higher.

composer require yiisoft/auth

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);
    // ...
}

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.

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 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.

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

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

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

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

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

• \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.

• 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.

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.