golang-jwt para Go: guia completo com exemplos

A biblioteca golang-jwt (nome oficial: github.com/golang-jwt/jwt/v5) é a implementação padrão de fato para JSON Web Tokens (JWT) na linguagem Go. Ela oferece aos desenvolvedores um conjunto de ferramentas poderoso e flexível para criar, assinar, verificar e decodificar tokens JWT. JWT é uma forma compacta e autossuficiente de transmitir informações entre partes como um objeto JSON, que pode ser verificado por ser assinado digitalmente. Os tokens JWT são amplamente utilizados para autenticação, autorização e troca segura de dados em APIs REST, arquiteturas de microsserviços e aplicações web.

Por que usar esta biblioteca? No desenvolvimento web moderno com Go, praticamente qualquer aplicação que exija autenticação de usuários (como servidores de API, microsserviços, sistemas de login único) precisa lidar com JWT. A biblioteca golang-jwt cuida de toda a complexidade: geração e verificação de assinaturas (HMAC, RSA, ECDSA, EdDSA), parsing de cabeçalhos e payload, tratamento de campos padrão (exp, iat, iss, sub) e claims personalizados. Sem ela, seria necessário implementar manualmente operações criptográficas e parsing de JSON, o que pode gerar erros e vulnerabilidades.

Principais vantagens do golang-jwt: suporte completo à especificação RFC 7519, facilidade de uso com uma interface fluente, alta performance (utiliza a biblioteca padrão crypto), e possibilidade de extensão através de métodos de assinatura e validadores personalizados. A biblioteca é ativamente mantida pela comunidade, possui mais de 7 mil estrelas no GitHub e é usada em projetos como Kubernetes, Docker, Grafana e muitos outros.

Instalação

A instalação da biblioteca é feita da forma padrão do Go, usando go get. Certifique-se de ter o Go versão 1.18 ou superior (recomendado 1.21+).

go get github.com/golang-jwt/jwt/v5

Após executar o comando, a dependência será adicionada ao seu go.mod. Para importar a biblioteca no código, use:

import "github.com/golang-jwt/jwt/v5"

Início rápido — exemplo mínimo funcional

Vamos criar um exemplo simples: geração e verificação de um token JWT usando uma chave simétrica (HMAC-SHA256).

package main

import (
    "fmt"
    "time"
    "github.com/golang-jwt/jwt/v5"
)

func main() {
    // 1. Chave secreta (deve ser armazenada com segurança)
    secretKey := []byte("minha-chave-super-secreta-12345")

    // 2. Criação do token
    claims := jwt.MapClaims{
        "user_id": 12345,
        "role":    "admin",
        "exp":     time.Now().Add(time.Hour * 24).Unix(), // expira em 24 horas
        "iat":     time.Now().Unix(),                     // emitido em
    }

    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
    tokenString, err := token.SignedString(secretKey)
    if err != nil {
        panic(err)
    }
    fmt.Println("Token gerado:", tokenString)

    // 3. Verificação e parsing do token
    parsedToken, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
        // Verifica se o método de assinatura é HMAC
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, fmt.Errorf("método de assinatura inesperado: %v", token.Header["alg"])
        }
        return secretKey, nil
    })

    if err != nil {
        panic(err)
    }

    // 4. Extração dos claims
    if claims, ok := parsedToken.Claims.(jwt.MapClaims); ok && parsedToken.Valid {
        fmt.Printf("ID do usuário: %v\n", claims["user_id"])
        fmt.Printf("Função: %v\n", claims["role"])
    } else {
        fmt.Println("Token inválido")
    }
}