CakePHP4使用CakeDC/users插件时API错Token返回登录页如何返回401

问题原因 #

默认配置下CakeDC/Users插件会同时加载Web端的Session、表单认证器，API请求Token校验失败后会 fallback 到Web认证逻辑，触发登录页重定向，所以返回HTML内容。

解决步骤 #

1. 按请求类型区分认证逻辑 #

修改项目根目录下src/Application.php中的getAuthenticationService方法，针对Api前缀的请求单独配置认证规则，仅加载Token认证器，避免触发Web端重定向逻辑：

public function getAuthenticationService(ServerRequestInterface $request): AuthenticationServiceInterface
{
    $service = new AuthenticationService();
    $prefix = $request->getParam('prefix');

    // API前缀请求专属配置
    if ($prefix === 'Api') {
        // 仅加载Token认证器，不加载Web端相关认证器
        $service->loadAuthenticator('Authentication.Token', [
            'skipTwoFactorVerify' => true,
            'header' => 'authorization',
            'queryParam' => 'api_token',
            'tokenPrefix' => 'Token',        
            'unauthenticatedRedirect' => null
        ]);

        // 自定义未认证响应，直接返回401 JSON
        $service->setUnauthenticatedHandler(function (ServerRequestInterface $request, ResponseInterface $response) {
            return $response->withStatus(401)
                ->withHeader('Content-Type', 'application/json')
                ->withStringBody(json_encode([
                    'status' => 'error',
                    'message' => '无效或缺失API访问凭证'
                ]));
        });

        return $service;
    }

    // 原有Web端认证配置保持不变，放在此处即可
    // ... 你之前的Web登录相关认证逻辑
}

2. API前缀控制器补充配置 #

在src/Controller/Api/AppController.php的初始化方法中，禁用自动重定向配置：

public function initialize(): void
{
    parent::initialize();
    $this->loadComponent('RequestHandler', [
        'viewClassMap' => ['json' => 'Json']
    ]);
    $this->loadComponent('Authentication.Authentication', [
        'unauthenticatedRedirect' => null
    ]);
    
    // 可在此处配置不需要Token校验的公开接口
    // $this->Authentication->allowUnauthenticated(['index', 'view']);
}

3. 可选校验规则 #

确保API请求携带Accept: application/json请求头，或者在请求路径末尾加.json扩展名，框架会自动匹配JSON响应格式，不会返回HTML内容。

内容的提问来源于stack exchange，提问作者AtLeT