golang-jwt en Go: guía completa con ejemplos prácticos

La librería golang-jwt (nombre oficial: github.com/golang-jwt/jwt/v5) es la implementación estándar de facto de JSON Web Tokens (JWT) para el lenguaje Go. Proporciona a los desarrolladores un conjunto de herramientas potente y flexible para crear, firmar, verificar y decodificar tokens JWT. JWT es una forma compacta y autónoma de transmitir información entre partes como un objeto JSON, que puede ser verificado porque está firmado digitalmente. Los tokens JWT se utilizan ampliamente para autenticación, autorización e intercambio seguro de datos en APIs REST, arquitecturas de microservicios y aplicaciones web.

¿Para qué sirve esta librería? En el desarrollo web moderno con Go, prácticamente cualquier aplicación que requiera autenticación de usuarios (por ejemplo, servidores API, microservicios, sistemas de inicio de sesión único) necesita trabajar con JWT. La librería golang-jwt se encarga de toda la complejidad: generación y verificación de firmas (HMAC, RSA, ECDSA, EdDSA), análisis de cabeceras y payload, manejo de campos estándar (exp, iat, iss, sub) y claims personalizados. Sin ella, tendrías que implementar manualmente operaciones criptográficas y análisis JSON, lo que conlleva errores y vulnerabilidades.

Ventajas clave de golang-jwt: soporte completo de la especificación RFC 7519, facilidad de uso gracias a su interfaz fluida, alto rendimiento (usa la librería estándar crypto), y posibilidad de extensión mediante métodos de firma y validadores personalizados. La librería cuenta con un mantenimiento activo por parte de la comunidad, más de 7 mil estrellas en GitHub y se utiliza en proyectos como Kubernetes, Docker, Grafana y muchos otros.

Instalación

La instalación de la librería se realiza de la forma estándar en Go mediante go get. Asegúrate de tener instalado Go versión 1.18 o superior (se recomienda 1.21+).

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

Después de ejecutar el comando, la dependencia aparecerá en tu archivo go.mod. Para importar la librería en tu código, hazlo de la siguiente manera:

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

Inicio rápido — ejemplo mínimo funcional

Vamos a crear un ejemplo sencillo: generación y verificación de un token JWT usando una clave simétrica (HMAC-SHA256).

package main

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

func main() {
    // 1. Clave secreta (debe almacenarse de forma segura)
    secretKey := []byte("mi-clave-super-secreta-12345")

    // 2. Creación del token
    claims := jwt.MapClaims{
        "user_id": 12345,
        "role":    "admin",
        "exp":     time.Now().Add(time.Hour * 24).Unix(), // vigencia de 24 horas
        "iat":     time.Now().Unix(),                     // momento de creación
    }

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

    // 3. Verificación y análisis del token
    parsedToken, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
        // Verificamos que el método de firma sea HMAC
        if _, ok := token.Method.(*jwt.SigningMethodHMAC); !ok {
            return nil, fmt.Errorf("método de firma inesperado: %v", token.Header["alg"])
        }
        return secretKey, nil
    })

    if err != nil {
        panic(err)
    }

    // 4. Extracción de claims
    if claims, ok := parsedToken.Claims.(jwt.MapClaims); ok && parsedToken.Valid {
        fmt.Printf("ID de usuario: %v\n", claims["user_id"])
        fmt.Printf("Rol: %v\n", claims["role"])
    } else {
        fmt.Println("El token no es válido")
    }
}