当前位置：首页 > news >正文

listmonk API JWT负载设计：包含必要信息

news 2026/6/5 8:42:12

listmonk API JWT负载设计：包含必要信息

在现代Web应用中，API安全是至关重要的一环。JSON Web Token（JWT，一种紧凑的、URL安全的方式，用于表示在双方之间传递的声明）作为一种流行的认证机制，其负载设计直接影响系统的安全性和灵活性。本文将深入探讨listmonk API的JWT负载设计，分析其中包含的必要信息及其在实际应用中的作用。

JWT负载基础

JWT由三部分组成：头部（Header）、负载（Payload）和签名（Signature）。负载部分包含了一些声明，这些声明是关于实体（通常是用户）和其他数据的声明。标准中定义了一些注册的声明，如iss（签发者）、exp（过期时间）、sub（主题）等，同时也允许自定义声明。

在listmonk项目中，JWT相关的处理逻辑主要集中在internal/auth/auth.go文件中。通过分析该文件，我们可以了解到listmonk是如何生成和验证JWT的，以及负载中包含哪些关键信息。

listmonk JWT负载核心字段

用户身份标识

用户身份标识是JWT负载中最基本也是最重要的信息之一。在listmonk中，用户身份通过用户ID来标识。在internal/auth/auth.go的代码中，我们可以看到在验证会话时，会从会话中获取用户ID，并据此查询用户信息。

// validateSession checks if the cookie session is valid (in the DB) and returns the session and user details. func (o *Auth) validateSession(c echo.Context) (*simplesessions.Session, User, error) { // Cookie session. sess, err := o.sess.Acquire(context.TODO(), c, c) if err != nil { return nil, User{}, echo.NewHTTPError(http.StatusForbidden, err.Error()) } // Get the session variables. vars, err := sess.GetMulti("user_id", "oidc_token") if err != nil { return nil, User{}, echo.NewHTTPError(http.StatusInternalServerError, err.Error()) } // Validate the user ID in the session. userID, err := o.sessStore.Int(vars["user_id"], nil) if err != nil || userID < 1 { o.log.Printf("error fetching session user ID: %v", err) return nil, User{}, echo.NewHTTPError(http.StatusInternalServerError, "invalid session.") } // Fetch user details from the database. user, err := o.cb.GetUser(userID) if err != nil { o.log.Printf("error fetching session user: %v", err) } return sess, user, err }

虽然上述代码是关于会话验证的，但从中可以推断出用户ID在身份验证中的核心地位。在JWT负载中，类似地会包含用户ID，以便API服务能够快速识别用户身份。

权限与角色信息

除了用户身份，权限与角色信息也是JWT负载中的重要组成部分。listmonk项目中定义了详细的用户角色和权限机制，这在models/models.go中有所体现。

// Perm is an HTTP handler middleware that checks if the authenticated user has the required permissions. func (o *Auth) Perm(next echo.HandlerFunc, perms ...string) echo.HandlerFunc { return func(c echo.Context) error { u, ok := c.Get(UserHTTPCtxKey).(User) if !ok { c.Set(UserHTTPCtxKey, echo.NewHTTPError(http.StatusForbidden, "invalid session")) return next(c) } // If the current user is a Super Admin user, do no checks. if u.UserRole.ID == SuperAdminRoleID { return next(c) } // Check if the current handler's permission is in the user's permission map. var ( has = false perm = "" ) for _, perm = range perms { if _, ok := u.PermissionsMap[perm]; ok { has = true break } } if !has { return echo.NewHTTPError(http.StatusForbidden, fmt.Sprintf("permission denied: %s", perm)) } return next(c) } }

从上述代码可以看出，listmonk会根据用户的角色和权限来控制对API的访问。因此，在JWT负载中包含用户的角色ID和权限信息，可以避免每次请求都需要查询数据库来获取用户权限，从而提高API的性能。

令牌相关信息

令牌的过期时间（exp）是JWT负载中必不可少的字段，它用于控制令牌的有效期，减少令牌被盗用后的风险。在listmonk中，虽然没有直接在internal/auth/auth.go中看到设置JWT过期时间的代码，但在会话管理中，设置了会话的最大存活时间。

// Initialize session manager. a.sess = simplesessions.New(simplesessions.Options{ EnableAutoCreate: false, SessionIDLength: 64, Cookie: simplesessions.CookieOptions{ IsHTTPOnly: true, MaxAge: time.Hour * 24 * 7, }, })

这段代码设置了会话Cookie的最大存活时间为7天。在JWT中，类似地会设置exp字段来指定令牌的过期时间。此外，可能还会包含iat（签发时间）等字段，用于跟踪令牌的生成时间。

自定义声明的应用

除了标准声明外，listmonk的JWT负载中还可能包含一些自定义声明，以满足特定的业务需求。例如，在处理OIDC（OpenID Connect）认证时，会获取用户的一些基本信息，如邮箱、姓名等。

type OIDCclaim struct { Email string `json:"email"` EmailVerified bool `json:"email_verified"` Sub string `json:"sub"` Picture string `json:"picture"` Name string `json:"name"` PreferredUsername string `json:"preferred_username"` }

这些信息可以作为自定义声明包含在JWT负载中，以便在API请求中快速获取用户的基本信息，而无需再次查询数据库。

JWT负载设计最佳实践

最小权限原则

在设计JWT负载时，应遵循最小权限原则，只包含必要的信息。过多的敏感信息存储在JWT中，一旦令牌被泄露，可能会导致安全风险。例如，用户的密码等敏感信息绝对不应该包含在JWT负载中。

合理设置过期时间

令牌的过期时间应根据应用的安全需求和用户体验进行权衡。过期时间过短，会导致用户频繁需要重新认证；过期时间过长，则会增加令牌被盗用的风险。listmonk中会话的默认过期时间为7天，在实际应用中，可以根据具体情况调整JWT的exp字段值。

确保负载信息的完整性和真实性

JWT的签名机制可以确保负载信息在传输过程中不被篡改。在listmonk中，虽然没有直接看到JWT签名的代码，但在处理OIDC认证时，会验证ID令牌的签名。

verifier, err := o.getVerifier() if err != nil { return "", OIDCclaim{}, echo.NewHTTPError(http.StatusUnauthorized, fmt.Sprintf("error getting verifier: %v", err)) } idTk, err := verifier.Verify(context.TODO(), rawIDTk) if err != nil { return "", OIDCclaim{}, echo.NewHTTPError(http.StatusUnauthorized, fmt.Sprintf("error verifying ID token: %v", err)) }

这段代码验证了从OIDC提供商获取的ID令牌的签名，确保令牌的完整性和真实性。在生成JWT时，也应使用安全的签名算法（如HS256、RS256等），并妥善保管签名密钥。