README

这是一个适用于 Slim 3.0+ 的 Token 认证中间件。此中间件旨在通过自定义验证器实现易于实现的 Token 认证。

安装

使用 Composer 获取最新版本。

composer require dyorg/slim-token-authentication

获取认证

首先创建一个 authenticator 函数，此函数将执行您应用程序的 Token 验证。在创建 TokenAuthentication 的新实例时，您必须传递一个包含配置选项的数组。您需要设置验证器和路径选项以启动认证。

$authenticator = function($request, TokenAuthentication $tokenAuth){

    # Search for token on header, parameter, cookie or attribute
    $token = $tokenAuth->findToken($request);
    
    # Your method to make token validation
    $user = User::auth_token($token);
    
    # If occured ok authentication continue to route
    # before end you can storage the user informations or whatever
    ...
    
};

$app = new App();

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator
]));

查找 Token

此中间件包含 findToken() 方法，您可以通过 TokenAuthentication 实例的第二个参数（TokenAuthentication 实例）访问它。此方法能够通过选项设置在头部、参数、cookie 或属性中搜索认证令牌。

配置选项

路径

默认情况下，没有路由需要认证。您必须在 path 选项上设置一个或多个需要由认证限制的路由。

...

$app = new App();

$app->add(new TokenAuthentication([
    'path' => '/api', /* or ['/api', '/docs'] */
    'authenticator' => $authenticator
]));

透传

您可以通过在 passthrough 选项上设置来配置不需要认证的路由。

...

$app = new App();

$app->add(new TokenAuthentication([
    'path' => '/api',
    'passthrough' => '/api/auth', /* or ['/api/auth', '/api/test'] */
    'authenticator' => $authenticator
]));

头部

默认情况下，中间件尝试从 Authorization 头部中查找 Token。您可以使用 header 选项更改头部名称。期望在 Authorization 头部中的值格式为 Bearer <token>，它通过正则表达式进行匹配。如果您想不使用 Token 类型或使用其他 Token 类型（如 Basic <token>），您可以通过在 regex 选项上设置正则表达式模式来更改它。您可以通过将 header 选项设置为 null 来禁用通过头部进行认证。

...

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator,
    'header' => 'Token-Authorization-X',
    'regex' => '/Basic\s+(.*)$/i', /* for without token type can use /\s+(.*)$/i */
]));

参数

如果在头部中没有找到 Token，中间件将尝试查找 authorization 查询参数。您可以使用 parameter 选项更改参数名称。您可以通过将 parameter 选项设置为 null 来禁用通过参数进行认证。

...

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator,
    'parameter' => 'token'
]));

cookie

如果 Token 还未找到，中间件将尝试查找 authorization cookie。您可以使用 cookie 选项更改 cookie 名称。您可以通过将 cookie 选项设置为 null 来禁用通过 cookie 进行认证。

...

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator,
    'cookie' => 'token'
]));

参数

作为最后的手段，中间件将尝试查找路由的 authorization 参数。您可以使用 argument 选项更改参数名称。您可以通过将 argument 选项设置为 null 来禁用通过参数进行认证。

...

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator,
    'argument' => 'token'
]));

错误

默认情况下，在认证失败时，将发送一个带有消息（Invalid Token 或 Not found Token）和 Token（如果找到）的 JSON 格式响应，状态为 401 Unauthorized。您可以通过在 error 选项上设置可调用的函数来自定义它。

...

$error = function($request, $response, TokenAuthentication $tokenAuth) {
    $output = [];
    $output['error'] = [
        'msg' => $tokenAuth->getResponseMessage(),
        'token' => $tokenAuth->getResponseToken(),
        'status' => 401,
        'error' => true
    ];
    return $response->withJson($output, 401);
}

$app = new App();

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator
    'error' => $error
]));

此错误函数在 TokenAuthentication 捕获实现 UnauthorizedExceptionInterface 的可抛出类时被调用。

安全

令牌本质上等同于密码。您应该将其视为密码，并且始终使用 HTTPS。如果中间件检测到通过 HTTP 的不安全使用，它将返回未授权的消息 Required HTTPS for token authentication。对于本地的请求，此规则是放宽的。要允许不安全的使用，您必须手动将其设置为 false。

...

$app = new App();

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator,
    'secure' => false
]));

或者，您可以列出您的开发主机以启用 宽松 安全性。

...

$app->add(new TokenAuthentication([
    'path' => '/api',
    'authenticator' => $authenticator,
    'secure' => true,
    'relaxed' => ['localhost', 'your-app.dev']
]));

示例

请查看如何在 /example 中使用它。

许可证

MIT 许可证（MIT）。请参阅 许可证 获取更多信息。