Edit: How to Store JWT Secrets in Go (Golang)

Posts›How to Store JWT Secrets in Go (Golang)

PublishedView Live →

Title

Slug

Preview: https://jwtsecretgenerator.com/blog/how-to-store-jwt-secrets-in-go

⚠ Changing the slug will break existing links to this post.

Description / Excerpt

155 / 180 characters

Content (Markdown)

## Why JWT Secret Storage Matters in Go

Go services typically read `JWT_SECRET` at startup and pass it to `github.com/golang-jwt/jwt/v5`. That works locally, but production demands secrets that never land in git, validate before traffic arrives, and rotate without breaking in-flight tokens. A secret baked into a Docker image layer is as bad as committing it to GitHub.

This guide covers Base64 decoding from environment variables, Docker and Kubernetes injection, startup validation, signing and verification, and overlap rotation. For key-length basics, see the [JWT secret glossary](/glossary/jwt-secret) and [HS256 vs RS256](/compare/hs256-vs-rs256).

## Threat Model for Go JWT Services

Attackers target easy wins:

- **Environment leakage** via `kubectl describe`, crash reports, APM env capture, or `docker inspect`.
- **Image-layer secrets** from `ENV JWT_SECRET=...` in Dockerfiles instead of runtime injection.
- **Truncated secrets** — Base64 decoding to fewer than 32 bytes weakens HS256 against offline attacks.
- **No rotation** — one leak forges every token until discovery.

Assume eventual compromise: short access-token TTL, scheduled rotation, and never log secrets or bearer tokens. Generate keys with the [JWT Secret Generator](/tools/jwt-secret-generator) and follow the [Go guide](/guides/jwt-secret-generator/go).

## Signing and Verifying JWTs in Go

Centralize signing and verification so every handler shares algorithm constraints:

```go
type TokenService struct {
    secret []byte
    issuer string
}

func NewTokenService(secret []byte, issuer string) (*TokenService, error) {
    if len(secret) < 32 {
        return nil, errors.New("JWT secret must be at least 32 bytes for HS256")
    }
    return &TokenService{secret: secret, issuer: issuer}, nil
}

func (s *TokenService) Sign(subject string, ttl time.Duration) (string, error) {
    claims := jwt.MapClaims{
        "sub": subject, "iss": s.issuer,
        "exp": time.Now().Add(ttl).Unix(), "iat": time.Now().Unix(),
    }
    return jwt.NewWithClaims(jwt.SigningMethodHS256, claims).SignedString(s.secret)
}

func (s *TokenService) Verify(tokenString string) (jwt.MapClaims, error) {
    token, err := jwt.Parse(tokenString, func(t *jwt.Token) (interface{}, error) {
        if t.Method != jwt.SigningMethodHS256 {
            return nil, errors.New("unexpected signing method")
        }
        return s.secret, nil
    })
    if err != nil || !token.Valid {
        return nil, errors.New("invalid token")
    }
    return token.Claims.(jwt.MapClaims), nil
}
```

Always pin `SigningMethodHS256` in the key func—trusting the header's `alg` enables algorithm-confusion attacks.

## Base64 Decoding Environment Secrets

Secret managers often store Base64 to avoid newline issues. Decode and validate length explicitly:

```go
func LoadJWTSecretFromEnv(name string) ([]byte, error) {
    raw := os.Getenv(name)
    if raw == "" {
        return nil, fmt.Errorf("%s is not set", name)
    }
    decoded, err := base64.StdEncoding.DecodeString(raw)
    if err != nil {
        decoded = []byte(raw) // dev fallback for raw hex
    }
    if len(decoded) < 32 {
        return nil, fmt.Errorf("%s must decode to at least 32 bytes", name)
    }
    return decoded, nil
}
```

Document whether ops expects Base64 or hex. Mixed formats across environments cause silent verification failures.

## Docker and Kubernetes Secret Injection

**Docker Compose** — inject at runtime, never in the Dockerfile:

```yaml
services:
  api:
    image: myapp:latest
    environment:
      JWT_SECRET: ${JWT_SECRET}
    secrets:
      - jwt_secret
secrets:
  jwt_secret:
    file: ./secrets/jwt_secret.b64
```

**Kubernetes:**

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: jwt-signing-key
type: Opaque
stringData:
  JWT_SECRET: "<base64-or-hex-from-secret-manager>"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  template:
    spec:
      containers:
        - name: api
          image: myapp:latest
          env:
            - name: JWT_SECRET
              valueFrom:
                secretKeyRef:
                  name: jwt-signing-key
                  key: JWT_SECRET
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 8080
```

Restrict RBAC so only the API service account reads the Secret. Prefer External Secrets Operator syncing from AWS or GCP rather than committing Secret manifests to git.

## Loading Secrets From Files and Managers

Environment variables are the common path, but Kubernetes often mounts secrets as files:

```go
secretBytes, err := os.ReadFile("/run/secrets/jwt_secret")
if err != nil {
    log.Fatalf("Failed to read secret file: %v", err)
}
secret := strings.TrimSpace(string(secretBytes))
if secret == "" {
    log.Fatal("JWT secret file is empty")
}
```

In AWS, fetch from Secrets Manager at startup and keep the value in memory — do not re-read on every request. Always reject empty configuration before serving traffic.

When verifying, pin HMAC explicitly to block algorithm confusion (an attacker forging `alg: RS256` while your HS256 secret is misused as a key material source):

```go
token, err := jwt.ParseWithClaims(tokenString, &Claims{}, func(token *jwt.Token) (interface{}, error) {
    if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
        return nil, fmt.Errorf("unexpected signing method: %v", token.Header["alg"])
    }
    return jwtSecret, nil
})
```

Use `github.com/golang-jwt/jwt/v5` — not archived `dgrijalva/jwt-go` forks with known CVEs.

## Startup Validation Before Accepting Traffic

Fail boot on invalid configuration and smoke-test signing:

```go
func main() {
    secret, err := config.LoadJWTSecretFromEnv("JWT_SECRET")
    if err != nil {
        log.Fatalf("jwt config: %v", err)
    }
    tokenSvc, err := auth.NewTokenService(secret, "https://auth.example.com")
    if err != nil {
        log.Fatalf("jwt service: %v", err)
    }
    smoke, _ := tokenSvc.Sign("health-check", time.Minute)
    if _, err := tokenSvc.Verify(smoke); err != nil {
        log.Fatalf("jwt smoke verify failed: %v", err)
    }
    log.Fatal(newHTTPServer(tokenSvc).ListenAndServe())
}
```

Expose `/health/ready` only after validation so Kubernetes skips bad pods.

## Rotation with Multiple Secrets

During overlap, verify against `JWT_SECRET` and `JWT_SECRET_PREVIOUS`; sign only with current:

```go
func (s *RotatingTokenService) Verify(tokenString string) (jwt.MapClaims, error) {
    for _, secret := range [][]byte{s.current, s.previous} {
        if secret == nil {
            continue
        }
        svc, _ := NewTokenService(secret, s.issuer)
        if claims, err := svc.Verify(tokenString); err == nil {
            return claims, nil
        }
    }
    return nil, errors.New("invalid token")
}
```

Deploy new secret as current, keep old as previous, wait for max token TTL, then remove previous and roll pods. Generate new material with the [JWT Secret Generator](/tools/jwt-secret-generator)—never embed values in Go source.

## Common Security Pitfalls

- **Committing `.env`** — use `.env.example` with placeholders only.
- **Logging secrets on startup** — logs reach third-party aggregators.
- **`jwt.Parse` without algorithm checks** — always validate `t.Method`.
- **Secrets in ConfigMaps** — use Secret resources or external stores.
- **Shared staging/production keys** — staging breaches forge production tokens.

## Production Checklist

- [ ] Runtime injection (Docker/K8s/cloud), never baked into images
- [ ] Startup validates ≥ 32 bytes and runs sign/verify smoke test
- [ ] Algorithm pinned to HS256 (or RS256 with key-pair management)
- [ ] Secret files excluded from version control
- [ ] Kubernetes RBAC limits Secret access
- [ ] Rotation supports current + previous during overlap
- [ ] Access token TTL ≤ 15 minutes
- [ ] Logs exclude secrets and full JWT strings
- [ ] Separate secrets per environment

## Frequently Asked Questions

### Is it safe to store JWT secrets in environment variables in Go?

Acceptable when Kubernetes or your cloud platform injects them at runtime—not when hardcoded in Dockerfiles. Env vars are visible inside the container and in crash dumps, so pair them with RBAC, short TTL, and secrets-manager sync. Stricter setups read from AWS/GCP/Azure APIs at startup.

### Should JWT secrets be Base64-encoded in Go?

Base64 is transport encoding, not security. Decode before use and confirm at least 32 bytes for HS256. The [Go guide](/guides/jwt-secret-generator/go) shows end-to-end signing after loading the secret.

### How do I rotate JWT secrets in Kubernetes without downtime?

Set `JWT_SECRET` to the new value and `JWT_SECRET_PREVIOUS` to the old, then roll pods. Verifiers accept either key. After the longest access-token lifetime, remove previous and roll again.

### What is the minimum secure length for an HS256 JWT secret in Go?

At least 32 bytes (256 bits) of random data. Shorter keys weaken HMAC if an attacker captures a token. Use the [JWT Secret Generator](/tools/jwt-secret-generator) rather than password derivation. For asymmetric setups, see [HS256 vs RS256](/compare/hs256-vs-rs256).

### Why must I verify the signing method in Go's ParseWithClaims?

Without checking `token.Method.(*jwt.SigningMethodHMAC)`, some stacks can be tricked by algorithm confusion (for example presenting an RSA public key as if it were an HMAC secret). The method check is not optional in production verifiers.

1233 words · ~7 min readMarkdown guide →

Tags (5/8)

jwtgosecrets-managementdevopssecurity

Author Name

Status

Cover Image URL (optional)

Danger Zone

Deleting this post sets its status to "deleted". It can be recovered via the API.