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 实例）从您的认证器方法中访问它。此方法能够在头部、参数、cookie 或属性中搜索认证 token。您可以通过选项设置来配置它。

配置选项

路径

默认情况下，没有路由需要认证。您必须设置一个或多个受认证限制的路由，通过在 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'
]));

错误

默认情况下，如果认证失败，会发送一个以 json 格式包含消息（Invalid Token 或 Not found Token）和 token（如果找到）以及状态码 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 的可抛出类时，会调用此错误函数。

安全

tokens 实质上是密码。您应该像对待密码一样对待它们，并且您应该始终使用 HTTPS。如果中间件检测到通过 HTTP 的不安全使用，它会返回一个带有消息 Required HTTPS for token authentication 的未授权响应。对于本地主机的请求，此规则较为宽松。要允许不安全的使用，您必须手动将其设置为 false。

...

$app = new App();

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

或者，您可以将您的开发主机列出来以获得 relaxed 安全性。

...

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

示例

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

许可证

麻省理工学院许可证（MIT）。请参阅许可证获取更多信息。