yiisoft/auth

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.0 or higher.

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.

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.

Support the project

Follow updates

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.

auth's Issues

Remove scrutinizer

Separate identity repository for token

Decouple IdentityRepositoryInterface::findIdentityByToken to separate interface for yiisoft/user#3

IdentityWithTokenRepositoryInterface should not extend IdentityRepositoryInterface

I think the IdentityWithTokenRepositoryInterface should not extend the IdentityRepositoryInterface.

auth/src/IdentityWithTokenRepositoryInterface.php

Line 10 in 49d8774

interface IdentityWithTokenRepositoryInterface extends IdentityRepositoryInterface

Because each Identity in this repositori can be related with multiple tokens.

Add ability to specify request type in optional patterns

 Group::create("/products")
        ->withCors(Cors::class)
        ->routes()
        ->routes(
            Route::get('')
                ->action([ProductController::class, 'index'])
                ->name('product/index'),
            Route::get('/{id:\d+}')
                ->middleware(Authentication::class)
                ->action([ProductController::class, 'view'])
                ->name('product/view'),
            Route::post('')
                ->middleware(Authentication::class)
                ->action([ProductController::class, 'create'])
                ->name('product/create'),
            Route::post('/{id:\d+}')
                ->middleware(Authentication::class)
                ->action([ProductController::class, 'update'])
                ->name('product/update'),
            Route::delete('/{id:\d+}')
                ->middleware(Authentication::class)
                ->action([ProductController::class, 'delete'])
                ->name('product/delete'),
            Route::put('/{id:\d+}/undo')
                ->middleware(Authentication::class)
                ->action([ProductController::class, 'undo'])
                ->name('product/undo'),
            Route::post('/{id:\d+}/favorite')
                ->middleware(Authentication::class)
                ->action([ProductController::class, 'favorite'])
                ->name('product/favorite'),
            Route::delete('/{id:\d+}/favorite')
                ->middleware(Authentication::class)
                ->action([ProductController::class, 'cancelFavorite'])
                ->name('product/cancelFavorite'),
        ),

like product/view if user is login will return 'favorite': true, if not login will return 'favorite': false

but if is use Authentication middleware, must login.

is can use follow code

Authentication::class => [
        'class' => Authentication::class,
        '__construct()' => [
            'authenticationFailureHandler' => Reference::to(PassportRequestErrorHandler::class),
        ],
        'withOptionalPatterns()' => [
            'optional' => ['/en/products/[1-9]']
        ]
    ],

but delete,update action url is like to view.
what can i do?

Add check to non-empty pattern in `HttpHeader::withPattern()` method

Do we need to add such a check and throw exception if pattern empty?

Add support of `psr/http-message` version 2.0

Re-introduce authKey

During development authKey concept was moved to yiisoft/user package because it was used for "remember me" cookie only. It should be back and should be checked when restoring current user from session/cookie. That is because on password change or similarly important action we should invalidate:

1. All user sessions.
2. "remember me cookie" (this part is currently done in yiisoft/user).

Add interface for Token invalidation

Should we add the interface of service for a Identity Token invalidation?
Invalidated can be one token (by token and token type) or all user tokens (by identity id and optional token type)