How to Build a High‑Performance Stateless OAuth2 Auth Server in Go

Why OAuth2 for microservices

OAuth2 isolates credentials from services, enables fine‑grained scope‑based permission control, and provides a seamless single‑sign‑on experience, which are essential in a microservice ecosystem.

Three‑layer architecture

1. Authorization layer (TokenGranter)

Implements the Strategy pattern to handle different grant types (password, client_credentials, etc.). Each grant type is a separate TokenGranter implementation.

type TokenGranter interface {
    Grant(ctx context.Context, grantType string, client *ClientDetails, reader *TokenRequest) (*OAuth2Token, error)
}

Strategy encapsulation : each grant type has its own implementation.

Dynamic composition : a ComposeTokenGranter registers and combines grant strategies at startup.

Infinite extensibility : adding a new grant (e.g., Authorization Code) only requires a new implementation.

2. Service layer (TokenService)

Manages the token lifecycle – creation, refresh, and parsing.

type TokenService interface {
    CreateAccessToken(oauth2Details *OAuth2Details) (*OAuth2Token, error)
    RefreshAccessToken(refreshTokenValue string) (*OAuth2Token, error)
    GetOAuth2DetailsByAccessToken(tokenValue string) (*OAuth2Details, error)
    // ...
}

3. Storage layer (TokenStore & TokenEnhancer)

Uses JWT to achieve true statelessness, eliminating the need for Redis or database persistence.

func (j *JwtTokenEnhancer) Enhance(accessToken *OAuth2Token, oauth2Details *OAuth2Details) (*OAuth2Token, error) {
    claims := &CustomClaims{
        ClientId: oauth2Details.Client.ClientId,
        Username: oauth2Details.User.Username,
        Roles:    oauth2Details.User.Authorities,
        // ... other claims
    }
    // sign with secret key
    // ...
    return accessToken, nil
}

Stateless JWT benefits

Zero storage dependency – all required data is embedded in the token.

Pure CPU‑bound verification, eliminating network I/O and deserialization.

Horizontal scalability – no shared session state.

Verification latency drops from milliseconds to microseconds, enabling >200k QPS.

Security hardening

Graceful JWT key rotation

Multiple keys are supported; the first is the current signing key, the rest are historic keys used for verification.

func NewJwtTokenEnhancer(secrets ...string) storage.TokenEnhancer {
    return &jwtEnhancer{currentSecret: secrets[0], oldSecrets: secrets[1:]}
}

func (j *jwtEnhancer) KeyFunc(token *jwt.Token) (interface{}, error) {
    // try currentSecret first, then iterate oldSecrets
    // return error if none match
    return nil, errors.New("no valid secret found")
}

Efficient token revocation with short‑hash blacklist

Because JWTs are stateless, revocation is achieved by storing a short SHA‑256 hash of the token in Redis with a TTL matching the token’s remaining lifetime.

Compute sha256 of the token.

Take the first 4 bytes (8 hex characters) as shortHash.

Store shortHash in Redis using SETEX and check existence with EXISTS during validation.

func (s *JwtTokenStore) RevokeAccessToken(tokenValue string, ttl time.Duration) error {
    hash := sha256.Sum256([]byte(tokenValue))
    shortHash := hex.EncodeToString(hash[:4])
    return s.redis.SetEX(ctx, fmt.Sprintf("revoked:%s", shortHash), "1", ttl).Err()
}

High‑availability design

Hot configuration updates : keys, token TTLs, and cache policies are refreshed via Consul without restarting services.

Triple cache protection : empty‑value cache (prevent cache penetration), distributed mutex (prevent cache breakdown), random expiration (prevent cache avalanche).

Graceful degradation : if Redis is unavailable, revocation checks are temporarily bypassed to keep authentication functional.

Open‑source repository

GitHub: https://github.com/louis-xie-programmer/easyms.golang

Gitee: https://gitee.com/louis_xie/easyms.golang