JWT Tokens

​

Overview

​

Token Generation

​

Generation Function

func GenerateTokensAndSetCookies(user *users.User, c echo.Context) (string, error)

1. Generates an access token with 24-hour expiration
2. Sets the token in an HTTP-only cookie named Bearer
3. Sets a user ID cookie for client-side access
4. Returns the token string

​

Token Structure

​

Claims

​

Claims Structure (Go)

type Claims struct {
    Name   string `json:"name"`
    UserId string `json:"user_id"`
    jwt.Claims
}

​

Token Expiration

​

Access Token

• Duration: 24 hours
• Set at: Login time
• Calculation: time.Now().Add(24 * time.Hour)

expirationTime := time.Now().Add(24 * time.Hour)

​

Token Signing

​

Algorithm

• Method: HMAC-SHA256 (HS256)
• Secret: Retrieved from SESSION_KEY environment variable

​

Secret Key

func GetJWTSecret() string {
    return configs.GetSessionKey()
}

​

Token Generation Process

​

Step-by-Step

1. Create Claims

claims := &Claims{
    UserId: user.ID,
    Claims: jwt.MapClaims{
        "exp": expirationTime.Unix(),
    },
}

2. Create Token with Algorithm

token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)

3. Sign Token

tokenString, err := token.SignedString(secret)

4. Set Cookies

setTokenCookie(accessTokenCookieName, accessToken, exp, c)
setUserCookie(user, exp, c)

​

Cookie Configuration

​

Bearer Cookie (Token Storage)

​

User Cookie (Client Access)

​

Token Validation

​

JWT Error Handler

func JWTErrorChecker(err error, c echo.Context) error {
    return c.Redirect(http.StatusMovedPermanently, c.Echo().Reverse("userSignInForm"))
}

• Token is expired
• Token signature is invalid
• Token is missing
• Token claims are malformed

​

Usage in Protected Routes

import (
    "github.com/labstack/echo/v4"
    echojwt "github.com/labstack/echo-jwt/v4"
)

// Configure JWT middleware
config := echojwt.Config{
    SigningKey:  []byte(auth.GetJWTSecret()),
    TokenLookup: "cookie:Bearer",
    ErrorHandler: auth.JWTErrorChecker,
}

// Apply to route group
protected := e.Group("/api")
protected.Use(echojwt.WithConfig(config))

​

Security Considerations

​

HTTP-Only Cookies

• Tokens stored in HTTP-only cookies are not accessible via JavaScript
• Prevents XSS attacks from stealing tokens
• Automatically sent with requests to the same domain

​

Token Expiration

• 24-hour expiration limits exposure window
• Expired tokens must re-authenticate
• No refresh token mechanism (yet)

​

Signing Secret

• Use strong, random SESSION_KEY (minimum 32 characters)
• Rotate secrets periodically in production
• Never commit secrets to version control

​

Algorithm Choice

• HS256 (HMAC-SHA256) provides:
  • Symmetric signing (same key for sign/verify)
  • Fast performance
  • Sufficient security for internal APIs

​

Token Lifecycle

1. Generation: User logs in successfully
2. Storage: Token stored in HTTP-only Bearer cookie
3. Usage: Automatically sent with each request
4. Validation: Echo JWT middleware validates on protected routes
5. Expiration: After 24 hours, token is no longer valid
6. Re-authentication: User must log in again

​

Example Token Payload

{
  "user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "",
  "exp": 1709654400
}

​

Source Code References

• Token generation: backend/auth/auth.go:29-46
• Claims structure: backend/auth/auth.go:22-26
• Cookie setting: backend/auth/auth.go:71-91
• Error handler: backend/auth/auth.go:94-97
• Secret retrieval: backend/auth/auth.go:18-20

​

Environment Configuration

SESSION_KEY=your-strong-secret-key-min-32-chars

openssl rand -base64 32