访问令牌验证器

访问令牌验证器支持使用可撤销的 API 令牌，而无需使用 OAuth。这些令牌通常用于向第三方开发者提供对你的 API 的访问权限。这些令牌通常具有非常长的过期时间，通常为数年。

这些令牌也适用于移动应用程序。在这种情况下，用户将使用其电子邮件/密码进行注册/登录。应用程序将为他们创建一个新的访问令牌，并使用一个可识别的名称，如 John's iPhone 12，并将其返回给移动应用程序，在移动应用程序中存储并用于所有未来的请求。

访问令牌/API 认证

使用访问令牌需要你使用/扩展 CodeIgniter\Shield\Models\UserModel 或在自己的用户模型上使用 CodeIgniter\Shield\Authentication\Traits\HasAccessTokens。此特性提供了在你的应用程序中实现访问令牌所需的所有自定义方法。必要的数据库表 auth_identities 在 Shield 唯一的迁移类中创建，在首次使用 Shield 的任何特性之前必须运行此迁移类。

生成访问令牌

访问令牌通过用户上的 generateAccessToken() 方法创建。这将令牌的名称作为第一个参数。该名称用于向用户显示，以便他们可以区分多个令牌。

$token = $user->generateAccessToken('Work Laptop');

这将使用加密安全的随机字符串创建令牌。在将令牌保存到数据库之前，对其进行哈希处理 (sha256)。该方法返回 CodeIgniters\Shield\Authentication\Entities\AccessToken 的一个实例。令牌的纯文本版本仅在创建后立即返回的 AccessToken 中可用。

应立即向用户显示纯文本版本，以便他们可以复制以供使用。如果用户丢失了它，他们将无法再看到原始版本，但他们可以生成一个新的令牌来使用。

$token = $user->generateAccessToken('Work Laptop');

// Only available immediately after creation.
echo $token->raw_token;

撤销访问令牌

可以通过 revokeAccessToken() 方法撤销访问令牌。这将纯文本访问令牌作为唯一参数。撤销只是从数据库中删除记录。

$user->revokeAccessToken($token);

通常，纯文本令牌作为身份验证过程的一部分从请求标头中检索。如果您需要以管理员身份撤销另一位用户的令牌，并且无法访问该令牌，则需要获取该用户的访问令牌并手动删除它们。

如果您没有可用于删除令牌的原始令牌，则可以使用存储在数据库中的令牌密钥来删除它。可以使用 accessTokens() 函数获取带有其密钥的所有令牌的列表。

$user->revokeAccessTokenBySecret($secret);

您可以使用 revokeAllAccessTokens() 方法撤销所有访问令牌。

$user->revokeAllAccessTokens();

检索访问令牌

以下方法可帮助您检索用户的访问令牌

// Retrieve a single token by plain text token
$token = $user->getAccessToken($rawToken);

// Retrieve a single token by it's database ID
$token = $user->getAccessTokenById($id);

// Retrieve all access tokens as an array of AccessToken instances.
$tokens = $user->accessTokens();

访问令牌范围

每个令牌都可以被赋予一个或多个它们可以在其中使用的范围。可以将它们视为令牌授予用户的权限。在生成令牌时提供范围，并且之后无法修改。

$token = $user->gererateAccessToken('Work Laptop', ['posts.manage', 'forums.manage']);

默认情况下，用户被授予一个通配符范围，该范围提供对所有范围的访问。这与

$token = $user->gererateAccessToken('Work Laptop', ['*']);

在身份验证期间，用户使用的令牌存储在用户上。经过身份验证后，您可以在用户上使用 tokenCan() 和 tokenCant() 方法来确定他们是否有权访问指定范围。

if ($user->tokenCan('posts.manage')) {
    // do something....
}

if ($user->tokenCant('forums.manage')) {
    // do something....
}

配置

根据您的需要配置 app/Config/AuthToken.php。

注意

Shield 不会期望您同时使用访问令牌验证器和 HMAC 验证器。因此，一些配置项是通用的。

访问令牌有效期

令牌将在使用后经过指定的时间后过期。

默认情况下，这设置为 1 年。您可以通过设置 $unusedTokenLifetime 值来更改此值。这是以秒为单位的，以便您可以使用 CodeIgniter 提供的时间常量。

public $unusedTokenLifetime = YEAR;

默认情况下，只有失败的登录尝试才会记录在 auth_token_logins 表中。

可以通过更改 $recordLoginAttempt 值来修改此设置。

public int $recordLoginAttempt = Auth::RECORD_LOGIN_ATTEMPT_FAILURE;

如果您不希望记录任何日志，请将其设置为 Auth::RECORD_LOGIN_ATTEMPT_NONE。

如果您希望记录所有登录尝试，请将其设置为 Auth::RECORD_LOGIN_ATTEMPT_ALL。这意味着您记录所有请求。

记录

根据上述配置，登录尝试记录在 auth_token_logins 表中。

当记录失败的登录尝试时，发送的原始令牌值将保存在 identifier 列中。

当记录成功的登录尝试时，令牌名称将保存在 identifier 列中。