hydrate

README

hydrate

A simple JWT authentication utility for Go

Installation

go get github.com/DOOduneye/hydrate

Features

• Generate Access and Refresh Tokens
• Verify Access and Refresh Tokens
• Set Custom Claims and Standard Claims
• Expire Tokens
• Middleware for Gin and Echo
• Token Blacklisting / Revoking
• Testing

Documentation

Overview

hydrate provides a simple, flexible authentication mechanism built around JWT (JSON Web Tokens) for Go applications. It supports the generation, verification and refreshing of access and refresh tokens.

Example Usage:

import (

"fmt"
"time"

"github.com/golang-jwt/jwt"
"github.com/garrettladley/hydrate"

m "github.com/garrettladley/mattress"

)

func main() {
    access, err := hydrate.NewAccessTokenConfigBuilder([]byte("secret"))
    if err != nil {
        fmt.Println(err)
        return
    }

    access.WithStandardClaims(jwt.StandardClaims{
        ExpiresAt: time.Now().Add(1 * time.Hour).Unix(),
        Issuer:    "test",
        Audience:  "test",
    })

    access.WithCustomClaims(map[string]interface{}{
        "role": "admin",
    })

    refresh, err := hydrate.NewRefreshTokenConfigBuilder([]byte("secret"))
    if err != nil {
        fmt.Println(err)
        return
    }

    refresh.WithStandardClaims(jwt.StandardClaims{
        ExpiresAt: time.Now().Add(24 * time.Hour).Unix(),
    })

    auth := hydrate.NewAuth(
        hydrate.WithAccessTokenConfig(access),
        hydrate.WithRefreshTokenConfig(refresh),
    )

    accessToken, refreshToken, err := auth.GenerateTokenPair(jwt.SigningMethodHS256)
    if err != nil {
        fmt.Println(err)
        return
    }

    fmt.Println("Access Token:", *accessToken)
    fmt.Println("Refresh Token:", *refreshToken)
}

Index

• func WithAccessTokenConfig(config *TokenConfig) func(*Auth)
• func WithRefreshTokenConfig(config *TokenConfig) func(*Auth)
• type Auth
  • func NewAuth(options ...func(*Auth)) *Auth
  • func (a *Auth) ExtractClaims(tokenString string, signingMethod jwt.SigningMethod, ...) (jwt.MapClaims, error)
  • func (a *Auth) GenerateAccessToken(signingMethod jwt.SigningMethod) (*string, error)
  • func (a *Auth) GenerateRefreshToken(signingMethod jwt.SigningMethod) (*string, error)
  • func (a *Auth) GenerateTokenPair(signingMethod jwt.SigningMethod) (*string, *string, error)
  • func (a *Auth) IsValid(tokenString string, signingMethod jwt.SigningMethod, ...) bool
  • func (a *Auth) RefreshAccessToken(tokenString string, signingMethod jwt.SigningMethod) (*string, error)
  • func (a *Auth) VerifyAccessToken(tokenString string, signingMethod jwt.SigningMethod) (*jwt.Token, error)
  • func (a *Auth) VerifyRefreshToken(tokenString string, signingMethod jwt.SigningMethod) (*jwt.Token, error)
• type TokenConfig
  • func NewAccessTokenConfigBuilder(secretKey []byte) (*TokenConfig, error)
  • func NewRefreshTokenConfigBuilder(secretKey []byte) (*TokenConfig, error)
  • func NewTokenConfigBuilder(secretKey []byte) (*TokenConfig, error)
  • func (b *TokenConfig) Build() TokenConfig
  • func (b *TokenConfig) WithCustomClaims(claims map[string]interface{}) *TokenConfig
  • func (b *TokenConfig) WithStandardClaims(claims jwt.StandardClaims) *TokenConfig

Functions

func WithAccessTokenConfig

func WithAccessTokenConfig(config *TokenConfig) func(*Auth)

WithAccessTokenConfig sets the access token configuration on the Auth instance. Returns a function that sets the access token configuration.

func WithRefreshTokenConfig

func WithRefreshTokenConfig(config *TokenConfig) func(*Auth)

WithRefreshTokenConfig sets the refresh token configuration on the Auth instance. Returns a function that sets the refresh token configuration.

Types

type Auth

type Auth struct {
	AccessConfig  TokenConfig // Configuration for access tokens
	RefreshConfig TokenConfig // Configuration for refresh tokens
}

Auth configures and manages token generation and validation for access and refresh tokens. It encapsulates configurations for both token types, allowing for separate secrets and claims. Also supports additional token configurations for other token types.

func NewAuth

func NewAuth(options ...func(*Auth)) *Auth

NewAuth creates a new Auth instance with the provided access and refresh token configurations. The access and refresh token configurations are used to generate and verify tokens.

func (*Auth) ExtractClaims

func (a *Auth) ExtractClaims(tokenString string, signingMethod jwt.SigningMethod, secretKey *m.Secret[[]byte]) (jwt.MapClaims, error)

ExtractClaims extracts the claims from a token. Returns the claims, or an error if one occurs.

func (*Auth) GenerateAccessToken

func (a *Auth) GenerateAccessToken(signingMethod jwt.SigningMethod) (*string, error)

GenerateAccessToken generates a new access token using the configured options. Will overwrite any custom claims with the provided standard claims. Returns the access token, or an error if one occurs.

func (*Auth) GenerateRefreshToken

func (a *Auth) GenerateRefreshToken(signingMethod jwt.SigningMethod) (*string, error)

GenerateRefreshToken generates a new refresh token using the configured options. Will overwrite any custom claims with the provided standard claims. Returns the refresh token, or an error if one occurs.

func (*Auth) GenerateTokenPair

func (a *Auth) GenerateTokenPair(signingMethod jwt.SigningMethod) (*string, *string, error)

GenerateTokenPair generates a new access and refresh token pair using the configured options. Returns the access and refresh tokens, or an error if one occurs.

func (*Auth) IsValid

func (a *Auth) IsValid(tokenString string, signingMethod jwt.SigningMethod, secretKey *m.Secret[[]byte]) bool

IsValid checks if a token is valid using the provided signing method and secret key. Returns true if the token is valid, otherwise false.

func (*Auth) RefreshAccessToken

func (a *Auth) RefreshAccessToken(tokenString string, signingMethod jwt.SigningMethod) (*string, error)

RefreshAccessToken refreshes the access token using the configured options. Returns the new access token, or an error if one occurs.

func (*Auth) VerifyAccessToken

func (a *Auth) VerifyAccessToken(tokenString string, signingMethod jwt.SigningMethod) (*jwt.Token, error)

VerifyAccessToken verifies an access token using the configured options. Returns the token, or an error if one occurs.

func (*Auth) VerifyRefreshToken

func (a *Auth) VerifyRefreshToken(tokenString string, signingMethod jwt.SigningMethod) (*jwt.Token, error)

VerifyRefreshToken verifies a refresh token using the configured options. Returns the token, or an error if one occurs.

type TokenConfig

type TokenConfig struct {
	// contains filtered or unexported fields
}

TokenConfig defines the configuration for tokens. These include the secret key, standard claims, and custom claims.

func NewAccessTokenConfigBuilder

func NewAccessTokenConfigBuilder(secretKey []byte) (*TokenConfig, error)

NewAccessTokenConfigBuilder instantiates a new instance of AccessTokenConfig with the provided secret key. If the secret key is nil, an error is returned.

func NewRefreshTokenConfigBuilder

func NewRefreshTokenConfigBuilder(secretKey []byte) (*TokenConfig, error)

NewRefreshTokenConfigBuilder instantiates a new instance of RefreshTokenConfig with the provided secret key. If the secret key is nil, an error is returned.

func NewTokenConfigBuilder

func NewTokenConfigBuilder(secretKey []byte) (*TokenConfig, error)

NewTokenConfigBuilder instantiates a new instance of TokenConfig with the provided secret key. If the secret key is nil, an error is returned.

func (*TokenConfig) Build

func (b *TokenConfig) Build() TokenConfig

Build builds the token configuration. Returns the built configuration instance.

func (*TokenConfig) WithCustomClaims

func (b *TokenConfig) WithCustomClaims(claims map[string]interface{}) *TokenConfig

WithCustomClaims sets the custom claims for the token. Returns the builder instance to allow for method chaining.

func (*TokenConfig) WithStandardClaims

func (b *TokenConfig) WithStandardClaims(claims jwt.StandardClaims) *TokenConfig

WithStandardClaims sets the standard claims for the token. Returns the builder instance to allow for method chaining.