README

VanillaConnect 库包含使用 PHP 项目与 VanillaConnect 插件一起所需的一切。

工作原理

作为提供者，您将收到经过签名的身份验证请求。如果发出请求的用户当前已登录，您将能够发出包含用户信息（也称为 "声明") 的身份验证响应，从而在您的论坛上登录用户。

客户端ID & 密钥

客户端ID 用于识别身份验证请求的发出者。它将指定在 JSON Web Token (JWT) 中。这告诉您身份验证请求来自“哪里”。

密钥 用于签名 JWT。这确保了发出者和提供者就是他们所说的那样。 切勿向任何人泄露或提供您的密钥。

声明

声明是 JWT 的“主体”。在身份验证请求时，您需要提供用户信息，以便我们可以在响应 JWT 中放入它们。

通常，响应的声明包含以下字段

• id: 您平台上的用户的 唯一 标识符。这通常是数字，但可以是任何字符串。
• name: 用户的名称。
• email: 用户的电子邮件。
• photourl: 用户的照片 URL。
• roles: Vanilla 的角色名称的逗号分隔列表。

所有这些都是可选的，但“id”。如果您想自动在 Vanilla 的另一侧创建用户，则“name”和“email”是必需的。

URL 白名单

提供者需要将所有可以接收响应的 URL 列出白名单。

为什么？

这项安全措施确保身份验证响应被发送到受信任的方。当进行身份验证请求时，JWT 的声明将包含应发送身份验证响应的重定向 URL。该 URL 必须由提供者“白名单”指定，否则响应的声明将被替换为错误。

如何操作？

您只需创建一个包含所有白名单 URL 的列表 {Scheme}{UserPwd}{Host}{Path}。

如果您 真的需要，您可以使用通配符（*）指定 URL 的这部分可以是任何内容。最好尽量避免使用通配符，因为它们会降低白名单的安全性。

• 方案：可以是 https://、http:// 或 //，如果您想同时允许两者。 您不能在这里使用通配符。
• UserPwd: (可选) 您可能不需要这个。看起来像这样： user:password@。
• Host: 可以是 IP 地址或域名。您可以可选地指定端口号。
  • 请注意，对于域名，出于安全原因，您不能在顶级域名或主域名中使用通配符。
• 路径：必须以/开头。通常，它应该是/authenticate/vanilla-connect/{clientID}

示例：https://forum.yourdomain.com/authenticate/vanilla-connect/1234。

注意事项：

• URL的查询字符串和片段部分未经验证，且不得存在于白名单URL中。
• 验证不区分大小写。

更多示例请查看使用示例部分。

使用示例

// If you did not use composer to install this library uncomment the following line.
//require_once PATH_TO_VANILLA_CONNECT_FOLDER.'/vendor/autoload.php';

// 1. Get the JSON Web Token from the URL.
$jwt = $_GET['jwt'];

// 2. Grab the current user from your session management system or database.
// Example: $userInfo = getUserInfo();

// If no user is logged in, you should redirect to your login page while preserving the JWT
// and once the user is logged in you redirect back to this page with the JWT.
// Example:
// https://yourdomain.com/vanilla-connect?jwt={TOKEN} // The user is not logged so redirect.
// https://yourdomain.com/signin?redirect=%2Fvanilla-connect%3Fjwt%3D{TOKEN} // The user logs in. Redirect back to vanilla-connect.
// https://yourdomain.com/vanilla-connect?jwt={TOKEN} // Now you should have the user informations.

// 3. Fill in the user information in a way that Vanilla can understand.
$user = [];

// Example:
// $claim['id'] = $user['UserID']; // This (the 'id item') is required no matter what.
// $claim['name'] = $user['UserName'];
// $claim['email'] = $user['Email'];
// $claim['photourl'] = $user['AvatarURL'];

// 4. Get your client ID and secret here. These must match those in your VanillaConnect settings.
$clientID = "1234";
$secret = "1234";

// 5. Create a whitelist of URLs that are safe to redirect to.
$whitelist = [];

// Example:
// $whitelist = [
//     "https://forum.production.mydomain.com/authenticate/vanilla-connect/".rawurlencode($clientID),
//     "https://forum.stage.mydomain.com/authenticate/vanilla-connect/".rawurlencode($clientID),
// ];

// 6. Validate the request and redirect back to the issuer with the response.
try {
    $vanillaConnect = new VanillaConnectProvider($clientID, $secret, $whitelist);
    $responseURL = $vanillaConnect->createResponseURL($jwt, $claim);
    header("Location: $responseURL");
    exit();
} catch (Exception $e) {
    // Something went wrong.
}