Segregate the methods of the AuthenticationMethodInterface

CHANGELOG.md

@@ -6,6 +6,7 @@
 - Enh #104: Explicitly mark readonly properties (@vjik)
 - Enh #105: Explicitly import classes and functions in "use" section (@mspirkov)
 - Enh #107: Remove unnecessary files from Composer package (@mspirkov)
+- Enh #113: Segregate the methods of the AuthenticationMethodInterface (@klsoft-web)
 
 ## 3.2.1 December 17, 2025
 

README.md

@@ -33,12 +33,12 @@ Configure a middleware and add it to your middleware stack:
 
 ```php
 $identityRepository = getIdentityWithTokenRepository(); // \Yiisoft\Auth\IdentityRepositoryInterface
-$authenticationMethod = new \Yiisoft\Auth\Method\HttpBasic($identityRepository);
+$authenticator = new \Yiisoft\Auth\Method\HttpBasic($identityRepository);
+$failureHandler = new \Yiisoft\Auth\Handler\AuthenticationFailureHandler($responseFactory);
 
 $middleware = new \Yiisoft\Auth\Middleware\Authentication(
-    $authenticationMethod,
-    $responseFactory, // PSR-17 ResponseFactoryInterface
-    $failureHandler // optional, \Yiisoft\Auth\Handler\AuthenticationFailureHandler by default
+    $authenticator,
+    $failureHandler
 );
 
 $middlewareDispatcher->addMiddleware($middleware);
@@ -47,7 +47,7 @@ $middlewareDispatcher->addMiddleware($middleware);
 In order to get an identity instance in the following middleware use `getAttribute()` method of the request instance:
 
 ```php
-public function actionIndex(\Psr\Http\Message\ServerRequestInterface $request): \Psr\Http\Message\ResponseInterface
+public function index(\Psr\Http\Message\ServerRequestInterface $request): \Psr\Http\Message\ResponseInterface
 {
     $identity = $request->getAttribute(\Yiisoft\Auth\Middleware\Authentication::class);
     // ...
@@ -60,7 +60,7 @@ Basic HTTP authentication is typically used for entering login and password in t
 Credentials are passed as `$_SERVER['PHP_AUTH_USER']` and `$_SERVER['PHP_AUTH_PW']`.
 
 ```php
-$authenticationMethod = (new \Yiisoft\Auth\Method\HttpBasic($identityRepository))
+$authenticator = (new \Yiisoft\Auth\Method\HttpBasic($identityRepository))
     ->withRealm('Admin')
     ->withAuthenticationCallback(static function (
         ?string $username,
@@ -79,15 +79,15 @@ Custom authentication callback set in the above is the same as default behavior
 Bearer HTTP authentication is typically used in APIs. Authentication token is passed in `WWW-Authenticate` header.
 
 ```php
-$authenticationMethod = new \Yiisoft\Auth\Method\HttpBearer($identityRepository);
+$authenticator = 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:
 
 ```php
- $authenticationMethod = (new \Yiisoft\Auth\Method\HttpHeader($identityRepository))
+ $authenticator = (new \Yiisoft\Auth\Method\HttpHeader($identityRepository))
      ->withHeaderName('X-Api-Key')
      ->withPattern('/(.*)/'); // default
 ```
@@ -100,14 +100,14 @@ This authentication method is mainly used by clients unable to send headers. In
 we advise not to use it.
 
 ```php
-$authenticationMethod = (new \Yiisoft\Auth\Method\QueryParameter($identityRepository))
+$authenticator = (new \Yiisoft\Auth\Method\QueryParameter($identityRepository))
     ->withParameterName('token');
 ```
 
 ### HTTP cookie authentication
 
 ```php
-$authenticationMethod = (new \Yiisoft\Auth\Method\HttpCookie($identityRepository))
+$authenticator = (new \Yiisoft\Auth\Method\HttpCookie($identityRepository))
     ->withCookieName('access-token');
 ```
 
@@ -118,7 +118,7 @@ Typical authentication for websites by storing a token in a browser cookie.
 To use multiple authentication methods, use `Yiisoft\Auth\Method\Composite`:
 
 ```php
-$authenticationMethod = new \Yiisoft\Auth\Method\Composite([
+$authenticator = new \Yiisoft\Auth\Method\Composite([
     $bearerAuthenticationMethod,
     $basicAuthenticationMethod
 ]);

src/AuthenticationMethodInterface.php

@@ -4,30 +4,9 @@
 
 namespace Yiisoft\Auth;
 
-use Psr\Http\Message\ResponseInterface;
-use Psr\Http\Message\ServerRequestInterface;
-
 /**
- * The interface that should be implemented by individual authentication methods.
+ * @deprecated Use AuthenticatorInterface and optionally ChallengeInterface.
  */
-interface AuthenticationMethodInterface
+interface AuthenticationMethodInterface extends AuthenticatorInterface, ChallengeInterface
 {
-    /**
-     * Authenticates the identity based on information available from request.
-     *
-     * @param ServerRequestInterface $request Request to get identity information from.
-     *
-     * @return IdentityInterface|null An instance of identity or null if there is no match.
-     */
-    public function authenticate(ServerRequestInterface $request): ?IdentityInterface;
-
-    /**
-     * Adds challenge to response upon authentication failure.
-     * For example, some appropriate HTTP headers may be added.
-     *
-     * @param ResponseInterface $response Response to modify.
-     *
-     * @return ResponseInterface Modified response.
-     */
-    public function challenge(ResponseInterface $response): ResponseInterface;
 }

src/AuthenticatorInterface.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Auth;
+
+use Psr\Http\Message\ServerRequestInterface;
+
+/**
+ * The interface that should be implemented by individual authentication methods.
+ */
+interface AuthenticatorInterface
+{
+    /**
+     * Authenticates the identity based on information available from request.
+     *
+     * @param ServerRequestInterface $request Request to get identity information from.
+     *
+     * @return IdentityInterface|null An instance of identity or null if there is no match.
+     */
+    public function authenticate(ServerRequestInterface $request): ?IdentityInterface;
+}

src/ChallengeInterface.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Yiisoft\Auth;
+
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * The interface that should be implemented by response upon authentication failure.
+ */
+interface ChallengeInterface
+{
+    /**
+     * Adds challenge to response upon authentication failure.
+     * For example, some appropriate HTTP headers may be added.
+     *
+     * @param ResponseInterface $response Response to modify.
+     *
+     * @return ResponseInterface Modified response.
+     */
+    public function challenge(ResponseInterface $response): ResponseInterface;
+}

src/Method/Composite.php

@@ -6,17 +6,18 @@
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Yiisoft\Auth\AuthenticationMethodInterface;
+use Yiisoft\Auth\AuthenticatorInterface;
+use Yiisoft\Auth\ChallengeInterface;
 use Yiisoft\Auth\IdentityInterface;
 use RuntimeException;
 
 /**
  * Composite allows multiple authentication methods at the same time.
  */
-final class Composite implements AuthenticationMethodInterface
+final class Composite implements AuthenticatorInterface, ChallengeInterface
 {
     /**
-     * @param AuthenticationMethodInterface[] $methods
+     * @param AuthenticatorInterface[] $methods
      */
     public function __construct(
         private readonly array $methods,
@@ -25,8 +26,8 @@
     public function authenticate(ServerRequestInterface $request): ?IdentityInterface
     {
         foreach ($this->methods as $method) {
-            if (!$method instanceof AuthenticationMethodInterface) {
-                throw new RuntimeException('Authentication method must be an instance of ' . AuthenticationMethodInterface::class . '.');
+            if (!$method instanceof AuthenticatorInterface) {
+                throw new RuntimeException('Authentication method must be an instance of ' . AuthenticatorInterface::class . '.');
             }
 
             $identity = $method->authenticate($request);
@@ -41,7 +42,9 @@
     public function challenge(ResponseInterface $response): ResponseInterface
     {
         foreach ($this->methods as $method) {
-            $response = $method->challenge($response);
+            if($method instanceof ChallengeInterface) {
+                $response = $method->challenge($response);
+            }
         }
         return $response;
     }

src/Method/HttpBasic.php

@@ -6,7 +6,8 @@
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Yiisoft\Auth\AuthenticationMethodInterface;
+use Yiisoft\Auth\AuthenticatorInterface;
+use Yiisoft\Auth\ChallengeInterface;
 use Yiisoft\Auth\IdentityInterface;
 use Yiisoft\Auth\IdentityWithTokenRepositoryInterface;
 use Yiisoft\Http\Header;
@@ -28,7 +29,7 @@
  * RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
  * ```
  */
-final class HttpBasic implements AuthenticationMethodInterface
+final class HttpBasic implements AuthenticatorInterface, ChallengeInterface
 {
     private string $realm = 'api';
     private ?string $tokenType = null;
@@ -162,7 +163,7 @@
     {
         return array_map(
             static fn($value) => $value === '' ? null : $value,
             explode(':', base64_decode(substr($authToken, 6)), 2),
         );
     }
 

src/Method/HttpBearer.php

@@ -5,14 +5,15 @@
 namespace Yiisoft\Auth\Method;
 
 use Psr\Http\Message\ResponseInterface;
+use Yiisoft\Auth\ChallengeInterface;
 use Yiisoft\Http\Header;
 
 /**
  * Authentication method based on HTTP Bearer token.
  *
  * @see https://tools.ietf.org/html/rfc6750
  */
-final class HttpBearer extends HttpHeader
+final class HttpBearer extends HttpHeader implements ChallengeInterface
 {
     protected string $headerName = Header::AUTHORIZATION;
 

src/Method/HttpCookie.php

@@ -4,9 +4,8 @@
 
 namespace Yiisoft\Auth\Method;
 
-use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Yiisoft\Auth\AuthenticationMethodInterface;
+use Yiisoft\Auth\AuthenticatorInterface;
 use Yiisoft\Auth\IdentityInterface;
 use Yiisoft\Auth\IdentityWithTokenRepositoryInterface;
 
@@ -15,7 +14,7 @@
  *
  * @see https://tools.ietf.org/html/rfc6265
  */
-final class HttpCookie implements AuthenticationMethodInterface
+final class HttpCookie implements AuthenticatorInterface
 {
     private string $cookieName = 'access-token';
     private ?string $tokenType = null;
@@ -35,11 +34,6 @@ public function authenticate(ServerRequestInterface $request): ?IdentityInterfac
         return $this->identityRepository->findIdentityByToken($authToken, $this->tokenType);
     }
 
-    public function challenge(ResponseInterface $response): ResponseInterface
-    {
-        return $response;
-    }
-
     /**
      * @psalm-immutable
      */

src/Method/HttpHeader.php

@@ -5,9 +5,8 @@
 namespace Yiisoft\Auth\Method;
 
 use JetBrains\PhpStorm\Language;
-use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Yiisoft\Auth\AuthenticationMethodInterface;
+use Yiisoft\Auth\AuthenticatorInterface;
 use Yiisoft\Auth\IdentityInterface;
 use Yiisoft\Auth\IdentityWithTokenRepositoryInterface;
 
@@ -20,7 +19,7 @@
  * {@see IdentityWithTokenRepositoryInterface::findIdentityByToken()}
  * and passes the value of the `X-Api-Key` header. This implementation is used mainly for authenticating API clients.
  */
-class HttpHeader implements AuthenticationMethodInterface
+class HttpHeader implements AuthenticatorInterface
 {
     protected string $headerName = 'X-Api-Key';
 
@@ -43,11 +42,6 @@ public function authenticate(ServerRequestInterface $request): ?IdentityInterfac
         return null;
     }
 
-    public function challenge(ResponseInterface $response): ResponseInterface
-    {
-        return $response;
-    }
-
     /**
      * @param string $name The HTTP header name.
      *

src/Method/QueryParameter.php

@@ -4,9 +4,8 @@
 
 namespace Yiisoft\Auth\Method;
 
-use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Yiisoft\Auth\AuthenticationMethodInterface;
+use Yiisoft\Auth\AuthenticatorInterface;
 use Yiisoft\Auth\IdentityInterface;
 use Yiisoft\Auth\IdentityWithTokenRepositoryInterface;
 
@@ -15,7 +14,7 @@
 /**
  * QueryParameter supports the authentication based on the access token passed through a query parameter.
  */
-final class QueryParameter implements AuthenticationMethodInterface
+final class QueryParameter implements AuthenticatorInterface
 {
     private string $parameterName = 'access-token';
     private ?string $tokenType = null;
@@ -32,11 +31,6 @@ public function authenticate(ServerRequestInterface $request): ?IdentityInterfac
         return null;
     }
 
-    public function challenge(ResponseInterface $response): ResponseInterface
-    {
-        return $response;
-    }
-
     /**
      * @param string $name The parameter name for passing the access token.
      *