README

此扩展向Rose添加用户身份验证功能。

composer require rsthn/rose-ext-sentinel

数据库结构

以下表是Sentinel必需的。请注意，以下任何表都可以根据需要扩展，显示的列是必需的最小值。

CREATE TABLE users
(
    user_id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    created_at DATETIME NOT NULL,
    deleted_at DATETIME DEFAULT NULL,
    blocked_at DATETIME DEFAULT NULL,
    username VARCHAR(256) NOT NULL,
    password VARCHAR(96) NOT NULL
)
ENGINE=InnoDB CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci AUTO_INCREMENT=1;

CREATE INDEX users_created_at ON users (created_at);
CREATE INDEX users_deleted_at ON users (deleted_at);
CREATE INDEX users_blocked_at ON users (blocked_at);
CREATE INDEX users_username ON users (username, deleted_at);

CREATE TABLE permissions
(
    permission_id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(128) NOT NULL UNIQUE
)
ENGINE=InnoDB CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE TABLE user_permissions
(
    user_id INT NOT NULL,
    permission_id INT NOT NULL,
    flag INT DEFAULT 0,
    PRIMARY KEY (user_id, permission_id),
    FOREIGN KEY (user_id) REFERENCES users (user_id),
    FOREIGN KEY (permission_id) REFERENCES permissions (permission_id)
)
ENGINE=InnoDB CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE INDEX user_permissions_flag ON user_permissions (user_id, flag);

令牌授权

每当需要通过访问令牌进行授权（在Sentinel配置部分中将auth_bearer设置为true）时，请将以下表添加到您的数据库中。

CREATE TABLE tokens
(
    token_id INT PRIMARY KEY AUTO_INCREMENT,
    created_at DATETIME NOT NULL,
    deleted_at DATETIME DEFAULT NULL,
    blocked_at DATETIME DEFAULT NULL,
    user_id INT NOT NULL,
    token VARCHAR(128) NOT NULL UNIQUE,
    name VARCHAR(128) NOT NULL,
    FOREIGN KEY (user_id) REFERENCES users (user_id)
)
ENGINE=InnoDB CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci AUTO_INCREMENT=1;

CREATE INDEX tokens_user_id ON tokens (user_id, deleted_at);
CREATE INDEX tokens_token ON tokens (token, deleted_at);

CREATE TABLE token_permissions
(
    token_id INT NOT NULL,
    permission_id INT NOT NULL,
    flag INT DEFAULT 0,
    PRIMARY KEY (token_id, permission_id),
    FOREIGN KEY (token_id) REFERENCES tokens (token_id),
    FOREIGN KEY (permission_id) REFERENCES permissions (permission_id)
)
ENGINE=InnoDB CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

CREATE INDEX token_permissions_flag ON token_permissions (token_id, flag);

标识符封禁

Sentinel支持将尝试暴力破解系统的标识符列入黑名单。要使用此功能，请检查sentinel:access-required、sentinel:access-denied和sentinel:access-granted函数。

以下表是实现此功能必需的。

CREATE TABLE suspicious_identifiers
(
    identifier VARCHAR(512) NOT NULL,
    PRIMARY KEY (identifier),
    next_attempt_at DATETIME DEFAULT NULL,
    last_attempt_at DATETIME NOT NULL,
    count_failed INT DEFAULT 1,
    count_blocked INT DEFAULT 0,
    is_banned INT DEFAULT 0
)
ENGINE=InnoDB CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci AUTO_INCREMENT=1;

配置部分："Sentinel"

函数

(sentinel:password <password>)

计算给定密码的哈希值并返回它。明文密码在计算哈希值之前分别附加和附加suffix和prefix配置字段。哈希算法由hash配置字段设置。

(sentinel:status)

返回活动会话的认证状态（布尔值）。

(sentinel:auth-required)

如果活动会话未认证，则返回错误代码401。

(sentinel:permission-required <permissions>)

验证活动会话是否具有指定的权限。如果会话未认证，则返回401错误，如果未满足权限要求，则返回403错误。权限字符串包含由竖线（|）分隔的权限名称OR集，以及由与符号（&）分隔的AND集。

(sentinel:has-permission <permissions>)

验证活动会话是否具有指定的权限。返回布尔值。权限字符串包含权限名称集（参见sentinel:permission-required）。

(sentinel:case <case1> <result1> ... [default <default>])

检查活动用户对其中一个案例值的权限。返回相应的结果或默认结果（如果没有匹配则返回空字符串）。注意，每个案例结果应是一个值而不是一个块。每个案例字符串是权限名称集（参见sentinel:permission-required）。

(sentinel:case
    "admin"      "Has permission admin"
    "client"     "Has permission client"
    "x | y"      "Has permission x or y"
    "a & b & c"  "Has permission a, b and c"
)

(sentinel:level-required <level>)

验证活动用户是否满足指定的最小权限级别。级别是权限_id除以100。如果用户未认证，则返回错误代码401，如果未满足权限级别要求，则返回403错误。

(sentinel:has-level <level>)

验证活动用户是否满足指定的最小权限级别。级别是权限_id除以100。返回布尔值。

(sentinel:get-level [username])

返回活动会话用户的权限级别，如果提供了username，则返回该用户的权限级别。

(sentinel:validate <username> <password>)

验证提供的凭据是否有效，返回布尔值。

(sentinel:login <username> <password>)

验证提供的凭据是否有效，如果失败，则返回错误代码422并相应地设置error字段。如果成功，则打开会话并使用已认证用户的user字段加载数据。

请注意，如果检测到 Authorization: BASIC data 头部信息，Sentinel 将自动运行登录过程（不创建会话）。
并且配置中启用了 auth_basic 标志。

当使用 Apache 时，HTTP_AUTHORIZATION 头部信息不会发送到应用程序，但是通过在您的 .htaccess 中设置以下内容，它
将可供 Sentinel 使用。

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

(sentinel:authorize <token> [persistent=false])

检查 Sentinel 配置中的 auth_bearer 标志是否设置为 true，然后验证令牌的有效性并授权访问。错误时返回状态码 422 并相应设置 error 字段。

如果成功，只有在 persistent 标志设置为 true 时才会打开会话，并将与刚授权的令牌相关的用户数据加载到会话的 user 字段中。
中。

请注意，如果检测到 Authorization: BEARER token 头部信息，并且配置中启用了 auth_bearer，Sentinel 将自动运行授权过程（不创建会话）。
。

(sentinel:token-id)

返回活动会话的 token_id 或如果用户尚未认证或通过其他方式（例如常规登录）认证且没有令牌，则返回 null。

(sentinel:login-manual <data>)

启动会话并将指定的数据对象加载到 user 会话字段中，从而有效地创建（手动）一个认证会话。如果放置在会话中的数据实际上不存在于数据库中，请确保在您的 API 中仅使用 sentinel:auth-required 和 sentinel:logout 函数，所有其他查询数据库的函数都将失败。

(sentinel:login-user <user_id>)

验证用户是否存在并强制登录 不 任何密码。如果失败，则返回 422 并相应设置 error 字段。如果成功，则打开会话并将刚认证的用户的数据加载到会话的 user 字段中。

(sentinel:logout)

从活动会话中删除认证状态。请注意，此函数本身不删除会话，仅删除与用户相关的认证数据。之后使用 session:destroy 完全删除会话。

(sentinel:reload)

从数据库重新加载活动用户的会话数据和权限。

(sentinel:access-required <identifier> [message])

确保提供的标识符既没有被禁止也没有被阻止。如果未提供 message 参数，则使用默认错误消息，并返回状态码 409。

(sentinel:access-denied <identifier> [action='auto'] [wait-timeout=2] [block-timeout=30])

为指定的标识符注册一个访问被拒绝的尝试。返回一个表示对标识符采取的操作的字符串，有效的值是 auto、wait、block 或 ban。

(sentinel:access-granted <identifier> [unban=false])

为标识符授予访问权限，调用此函数将重置失败和阻止计数器。除非将 unban 参数设置为 true，否则禁止将继续生效。