henriqueatila/golang-gin-best-practices / skills/golang-gin-auth
golang-gin-auth
VerifiedJWT auth and RBAC for Go Gin APIs. Use when adding login, signup, JWT tokens, role checks, protected routes, or password hashing to a Gin app.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.4 KB |
| metadata.json | config | 499 B |
| references/auth-implementation-core.md | markdown | 3.5 KB |
| references/auth-implementation-handlers.md | markdown | 3.9 KB |
| references/auth-ip-rate-limiter.md | markdown | 1.5 KB |
| references/auth-middleware.md | markdown | 2.2 KB |
| references/captcha-middleware.md | markdown | 3.8 KB |
| references/jwt-patterns-blacklist.md | markdown | 3.4 KB |
| references/jwt-patterns-rs256.md | markdown | 2.7 KB |
| references/jwt-patterns-storage-and-csrf.md | markdown | 3.8 KB |
| references/jwt-patterns-tokens.md | markdown | 4.8 KB |
| references/oauth2-flows.md | markdown | 3.8 KB |
| references/oauth2-github-profile.md | markdown | 1.3 KB |
| references/oauth2-google-and-security.md | markdown | 2.0 KB |
| references/rbac-hierarchy-and-tenant.md | markdown | 3.2 KB |
| references/rbac-middleware.md | markdown | 4.2 KB |
| references/rbac-resource-and-impersonation.md | markdown | 3.8 KB |
| references/rbac-route-wiring.md | markdown | 1.6 KB |
references/jwt-patterns-tokens.md
View on GitHub# JWT Patterns — Token Architecture, Claims & Refresh Endpoint
See also: `jwt-patterns-blacklist.md`, `jwt-patterns-storage-and-csrf.md`, `jwt-patterns-rs256.md`
## Access + Refresh Token Architecture
Two-token strategy: short-lived access tokens reduce attack surface; long-lived refresh tokens enable session continuity without re-login.
```
┌──────────┐ POST /auth/login ┌───────────┐
│ Client │──────────────────────▶│ Gin API │
│ │◀──────────────────────│ │
│ │ {access, refresh} └───────────┘
│ │
│ │ GET /api/v1/users ┌───────────┐
│ │ Authorization: Bearer <access>
│ │──────────────────────▶│ Gin API │
│ │◀──────────────────────│ │
│ │ 200 OK └───────────┘
│ │
│ │ POST /auth/refresh ┌───────────┐
│ │ {refresh_token} │ │
│ │──────────────────────▶│ Gin API │
│ │◀──────────────────────│ │
│ │ {new_access} └───────────┘
└──────────┘
```
| Token | TTL | Payload | Stored where |
|---------------|------------|---------------|-----------------|
| Access token | 15 minutes | UserID, Role | Memory / header |
| Refresh token | 7–30 days | UserID only | httpOnly cookie |
---
## Custom Claims
Embed `jwt.RegisteredClaims` for standard fields. Add only what handlers need.
```go
// internal/auth/claims.go
package auth
import "github.com/golang-jwt/jwt/v5"
type Claims struct {
jwt.RegisteredClaims // sub, iat, exp, iss, aud
UserID string `json:"uid"`
Email string `json:"email"`
Role string `json:"role"`
}
// RefreshClaims is the minimal payload for refresh tokens.
// TokenID (jti) enables per-token revocation without invalidating all sessions.
type RefreshClaims struct {
jwt.RegisteredClaims
TokenID string `json:"jti"`
}
```
---
## Token Refresh Endpoint
Two rotation strategies — pick one:
- **Option A: Always rotate** — new refresh token on every call. More secure but breaks parallel requests using the same refresh token.
- **Option B: Rotate past half-lifetime (recommended)** — issue a new refresh token only when the current one is more than halfway through its lifetime.
```go
// internal/handler/auth_handler.go (Refresh method)
func (h *AuthHandler) Refresh(c *gin.Context) {
var req struct {
RefreshToken string `json:"refresh_token" binding:"required"`
}
if err := c.ShouldBindJSON(&req); err != nil {
c.JSON(http.StatusBadRequest, gin.H{"error": "invalid request body"})
return
}
token, err := jwt.ParseWithClaims(req.RefreshToken, &auth.RefreshClaims{}, func(t *jwt.Token) (any, error) {
if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
}
return h.tokenCfg.RefreshSecret, nil
})
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid or expired refresh token"})
return
}
rc, ok := token.Claims.(*auth.RefreshClaims)
if !ok || !token.Valid {
c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid refresh token claims"})
return
}
user, err := h.userRepo.GetByID(c.Request.Context(), rc.Subject)
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid or expired refresh token"})
return
}
accessToken, err := auth.GenerateAccessToken(h.tokenCfg, user.ID, user.Email, user.Role)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
return
}
resp := gin.H{
"access_token": accessToken,
"expires_in": int(h.tokenCfg.AccessTTL / time.Second),
}
// Option B: rotate only past half-lifetime
halfLife := rc.IssuedAt.Time.Add(h.tokenCfg.RefreshTTL / 2)
if time.Now().After(halfLife) {
newRefresh, err := auth.GenerateRefreshToken(h.tokenCfg, user.ID)
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
return
}
resp["refresh_token"] = newRefresh
}
c.JSON(http.StatusOK, resp)
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |