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-storage-and-csrf.md
View on GitHub# JWT Patterns — Storage Recommendations & CSRF Protection
See also: `jwt-patterns-tokens.md`, `jwt-patterns-blacklist.md`, `jwt-patterns-rs256.md`
## Storage Recommendations
Where the client stores tokens affects the attack surface:
| Storage | XSS Risk | CSRF Risk | Notes |
|-----------------|----------|-----------|------------------------------------------------|
| httpOnly cookie | Low | Medium | Use `SameSite=Strict` + CSRF token to mitigate |
| localStorage | High | Low | JavaScript-accessible — XSS can steal tokens |
| sessionStorage | High | Low | Same as localStorage, cleared on tab close |
| Memory (JS var) | Low | Low | Lost on refresh — needs silent refresh flow |
**Recommended:** httpOnly, Secure cookie for refresh token; short-lived access token in memory or Authorization header.
Setting a secure cookie in Gin — use `http.SetCookie` directly to set `SameSite`, which `c.SetCookie` does not expose:
```go
http.SetCookie(c.Writer, &http.Cookie{
Name: "refresh_token",
Value: refreshToken,
Path: "/auth", // restrict to /auth/* endpoints
HttpOnly: true, // not accessible by JavaScript
Secure: true, // HTTPS only
SameSite: http.SameSiteStrictMode, // CSRF mitigation
MaxAge: 7 * 24 * 3600, // 7 days in seconds
})
```
Reading the cookie in the refresh endpoint:
```go
refreshToken, err := c.Cookie("refresh_token")
if err != nil {
c.JSON(http.StatusUnauthorized, gin.H{"error": "refresh token not found"})
return
}
```
---
## CSRF Protection
When using httpOnly cookies for the refresh token, protect state-mutating endpoints from cross-site request forgery. The double-submit cookie pattern: set a non-httpOnly CSRF token cookie on login, require it in a custom header on every mutating request.
```go
// pkg/middleware/csrf.go
package middleware
import (
"crypto/hmac"
"net/http"
"github.com/gin-gonic/gin"
)
// CSRFProtection implements the double-submit cookie pattern.
func CSRFProtection() gin.HandlerFunc {
return func(c *gin.Context) {
method := c.Request.Method
if method == http.MethodGet || method == http.MethodHead || method == http.MethodOptions {
c.Next()
return
}
csrfHeader := c.GetHeader("X-CSRF-Token")
cookieToken, err := c.Cookie("csrf_token")
if err != nil || csrfHeader == "" || !hmac.Equal([]byte(csrfHeader), []byte(cookieToken)) {
c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "invalid CSRF token"})
return
}
c.Next()
}
}
```
**Set the CSRF cookie on login** (non-httpOnly so JavaScript can read it):
```go
func generateCSRFToken() (string, error) {
b := make([]byte, 32)
if _, err := rand.Read(b); err != nil {
return "", err
}
return hex.EncodeToString(b), nil
}
// Inside Login, after issuing tokens:
csrfToken, err := generateCSRFToken()
if err != nil {
c.JSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
return
}
http.SetCookie(c.Writer, &http.Cookie{
Name: "csrf_token",
Value: csrfToken,
Path: "/",
Secure: true,
HttpOnly: false, // must be readable by JS to send as header
SameSite: http.SameSiteStrictMode,
MaxAge: 7 * 24 * 3600,
})
```
Apply the middleware on all mutating routes:
```go
api := r.Group("/api/v1")
api.Use(middleware.CSRFProtection())
```
> **Note:** CSRF protection is only necessary when using cookies for auth. If you use `Authorization: Bearer` headers exclusively, CSRF is not a risk — browsers do not send custom headers cross-origin without explicit CORS preflight.
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: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |