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/captcha-middleware.md
View on GitHub# CAPTCHA Middleware — reCAPTCHA v2/v3 & hCaptcha
No additional Go packages needed. Uses only `net/http` and `encoding/json`.
## reCAPTCHA v2/v3 Verification
Google's `siteverify` endpoint accepts a POST with the secret key and the token submitted by the client.
```go
// internal/middleware/captcha.go
package middleware
import (
"context"
"encoding/json"
"log/slog"
"net/http"
"net/url"
"os"
"strings"
"github.com/gin-gonic/gin"
)
const (
recaptchaVerifyURL = "https://www.google.com/recaptcha/api/siteverify"
hcaptchaVerifyURL = "https://hcaptcha.com/siteverify"
)
type captchaResponse struct {
Success bool `json:"success"`
Score float64 `json:"score"` // reCAPTCHA v3 only
Action string `json:"action"` // reCAPTCHA v3 only
}
func verifyCaptcha(ctx context.Context, verifyURL, secretKey, token string) (bool, error) {
resp, err := http.PostForm(verifyURL, url.Values{
"secret": {secretKey},
"response": {token},
})
if err != nil {
return false, err
}
defer resp.Body.Close()
var result captchaResponse
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
return false, err
}
return result.Success, nil
}
```
## Middleware Implementation
```go
// CaptchaMiddleware verifies reCAPTCHA or hCaptcha tokens server-side.
func CaptchaMiddleware(secretKey, verifyURL string, logger *slog.Logger) gin.HandlerFunc {
return func(c *gin.Context) {
if os.Getenv("APP_ENV") == "test" {
c.Next()
return
}
token := c.GetHeader("X-Captcha-Token")
if token == "" {
token = c.PostForm("g-recaptcha-response")
}
if strings.TrimSpace(token) == "" {
c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "captcha token required"})
return
}
ok, err := verifyCaptcha(c.Request.Context(), verifyURL, secretKey, token)
if err != nil {
logger.Error("captcha verification request failed", "error", err)
c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{"error": "internal error"})
return
}
if !ok {
c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "captcha verification failed"})
return
}
c.Next()
}
}
func HCaptchaMiddleware(logger *slog.Logger) gin.HandlerFunc {
return CaptchaMiddleware(os.Getenv("HCAPTCHA_SECRET"), hcaptchaVerifyURL, logger)
}
func ReCaptchaMiddleware(logger *slog.Logger) gin.HandlerFunc {
return CaptchaMiddleware(os.Getenv("RECAPTCHA_SECRET"), recaptchaVerifyURL, logger)
}
```
## Route Application
Apply CAPTCHA only to public-facing forms that are abuse vectors. Do not apply to authenticated routes.
```go
recaptcha := middleware.ReCaptchaMiddleware(logger)
authGroup := r.Group("/auth")
authGroup.Use(middleware.IPRateLimiter(5, time.Minute))
{
authGroup.POST("/register", recaptcha, authHandler.Register)
authGroup.POST("/login", authHandler.Login) // rate limiting is sufficient here
authGroup.POST("/forgot-password", recaptcha, authHandler.ForgotPassword)
}
public := r.Group("/")
{ public.POST("/contact", recaptcha, contactHandler.Submit) }
```
## Security Notes
- **Never trust client-side validation alone**: The browser widget can be bypassed; always verify server-side.
- **Secret key is server-only**: Never expose `RECAPTCHA_SECRET` to the client or commit to source control.
- **Test mode bypass**: Check `APP_ENV == "test"` to skip verification in automated tests without mocking HTTP calls.
- **Score threshold (v3)**: For reCAPTCHA v3, parse `score` from the response and reject requests below your threshold (typically `0.5`).
- **IP forwarding**: If behind a proxy, pass the client IP in the `remoteip` field of the verification request for better accuracy.
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 |