FeedbackTrace 社区

FeedbackTrace 支持单点登录（SSO），协议是基于 JWT 的自定义验证流程，需要你的用户登录服务开发一个接口。以下说明如何接入单点登录。

[!NOTE]
该功能未来可能变动，订阅此话题获取更新通知。

验证流程

用户在 FeedbackTrace 点击登录，重定向到预先设置的登录接口（例如 https://yoursite.com/sso/feedbacktrace）。
https://yoursite.com/sso/feedbacktrace 判断用户是否已登录 yoursite.com，如果未登录则需要转到登录流程。
如果用户已登录，用预配置的密钥生成 JWT，作为参数重定向到 FeedbackTrace 的 SSO 接口，例如 https://yoursite.com/auth/jwt/callback?token=JWT。注意为了防止滥用，应该使用表单或者 JS 二次提交后再重定向，不要直接重定向 GET 请求。
FeedbackTrace 接收到 JWT，解析其中的用户身份信息，创建新用户或登录已有用户。

接口和密钥

在管理后台（/admin）-> 设置 -> 认证，可以设置登录接口的地址，和获取 JWT 的签名密钥：

截屏2023-11-08 14.44.33.png

JWT

JSON Web Tokens(JWT) 是一个广泛应用的数据加签格式，官方提供了各个编程语言的库，详情可以查看 https://jwt.io/libraries 。

FeedbackTrace 当前使用 HS256 算法签名。用户认证需要 JWT 中包含的数据如下：

key	值示例	需求	说明
exp	1672531200	必须	Token 的过期时间，推荐设置 1 分钟后过期。超长的过期时间（目前为 30 分钟后）FeedbackTrace 也会认为无效。
external_id	u123456	必须	用户 ID，该值应该持久不变，如果改变将视为不同的用户。
email	user@example.com	推荐	邮箱地址，用于接收邮件通知，如果为空会在创建用户时需要用户补充。
name	User 123	推荐	用户全称，如果为空会在创建用户时需要用户补充。
username	user123	推荐	用户名，仅包含数字、英文、- 字符，站内唯一，用于 @mention 提及用户，如果为空会在创建用户时需要用户补充。

代码示例

以 Ruby on Rails 代码为例。

[!NOTE]
如果你使用其他语言或框架，我很乐意合作提供其他语言的集成示例，请在评论区留言。

在 config/routes.rb 中添加路由：

  # /sso/feedbacktrace
  namespace :sso do
    resource :feedbacktrace, controller: "feedbacktrace"
  end

添加控制器 app/controllers/sso/feedbacktrace_contorller.rb：

class Sso::FeedbacktraceController < ApplicationController
  before_action :require_sign_in

  def show
  end

  def create
    token = JWT.encode({
      exp: 1.minute.from_now.to_i,
      external_id: current_user.id,
      email: current_user.email,
      name: current_user.name,
      username: current_user.account.name
    }, Rails.configuration.x.feedbacktrace_jwt_sso_secret_key, "HS256")

    uri = URI(Rails.configuration.x.feedbacktrace_jwt_sso_callback_url)
    uri.query = URI.encode_www_form(token: token)

    redirect_to uri.to_s, allow_other_host: true
  end
end

添加模版 app/views/sso/feedbacktrace/show.html.erb：

  <%= form_with url: sso_feedbacktrace_path, method: :post, id: :sso_form, data: {turbo: false} do %>
    验证中...
  <% end %>
  <script>
    document.getElementById('sso_form').submit();
  </script>

在 config/application.rb 中添加配置：

    config.x.feedbacktrace_jwt_sso_callback_url = ENV['FEEDBACKTRACE_JWT_SSO_CALLBACK_URL']
    config.x.feedbacktrace_jwt_sso_secret_key = ENV['FEEDBACKTRACE_JWT_SSO_SECRET_KEY']

设置环境变量 FEEDBACKTRACE_JWT_SSO_CALLBACK_URL FEEDBACKTRACE_JWT_SSO_SECRET_KEY，然后重启服务。