ose_jwt

README

ose-jwt

ose-jwt is a Go package for managing JSON Web Tokens (JWT) with support for access tokens, refresh tokens, and purpose-specific tokens. It provides a structured way to include multi-tenant roles and permissions, as well as custom claims. The package is lightweight, secure, and easy to integrate.

---

✨ Features

• Issue JWTs for access, refresh, or purpose tokens
• Supports multi-tenant role and permission claims
• Include custom extra claims
• Parse and validate JWTs safely
• Automatically manages expiration and issued-at timestamps
• Uses UTC timestamps for consistency across systems

---

🚀 Installation

go get github.com/ose-micro/jwt

Usage

Initialize Manager

package main

import (
	"fmt"
	"time"

	ose_jwt "github.com/ose-micro/jwt"
)

func main() {
	cfg := ose_jwt.Config{
		Prefix:     "OSE",
		Secret:     []byte("super-secret-key"),
		Issuer:     "ose",
		AccessTTL:  15 * time.Minute,
		RefreshTTL: 7 * 24 * time.Hour,
		PurposeTTL: 30 * time.Minute,
	}

	manager, err := ose_jwt.NewManager(cfg)
	if err != nil {
		panic(err)
	}

	fmt.Println("JWT Manager initialized:", manager)
}

Issue Tokens

tenants := map[string]jwt.Tenant{
    "owner": {
        Role:   "admin",
        Tenant: "owner",
        Permissions: []common.Permission{
            {Resource: "campaign", Action: "create"},
            {Resource: "campaign", Action: "read"},
        },
    },
}

token, claims, err := manager.IssueAccessToken("user123", tenants, nil)
if err != nil {
    panic(err)
}

fmt.Println("Access Token:", token)
fmt.Println("Claims:", claims)

⚠ Warning: ParseClaimsUnsafe does not validate the token signature. Use it only for debugging or logging.

Helpers

Check tenant roles and permissions easily:

if jwt.HasTenantRole(*claims, "owner", "admin") {
    fmt.Println("User is an admin in the owner tenant")
}

perm := common.Permission{Resource: "campaign", Action: "create"}
if jwt.HasTenantPermission(*claims, "owner", perm) {
    fmt.Println("User can create campaigns")
}

License

MIT License © 2025 Moriba SL

Documentation

Index

• func HasTenantPermission(c Claims, tenantID string, perm common.Permission) bool
• func HasTenantRole(c Claims, tenantID, role string) bool
• type Claims
  • func (c Claims) GetAudience() (jwt.ClaimStrings, error)
  • func (c Claims) GetExpirationTime() (*jwt.NumericDate, error)
  • func (c Claims) GetIssuedAt() (*jwt.NumericDate, error)
  • func (c Claims) GetIssuer() (string, error)
  • func (c Claims) GetNotBefore() (*jwt.NumericDate, error)
  • func (c Claims) GetSubject() (string, error)
• type Config
• type Manager
  • func NewManager(config Config) (*Manager, error)
  • func (m *Manager) IssueAccessToken(sub string, tenants map[string]Tenant, extra map[string]any) (string, *Claims, error)
  • func (m *Manager) IssuePurposeToken(sub string, tenants map[string]Tenant, extra map[string]any) (string, *Claims, error)
  • func (m *Manager) IssueRefreshToken(sub string, tenants map[string]Tenant, extra map[string]any) (string, *Claims, error)
  • func (m *Manager) IssueToken(sub string, kind TokenKind, tenants map[string]Tenant, extra map[string]any, ...) (string, error)
  • func (m *Manager) ParseClaims(tokenStr string) (*Claims, error)
  • func (m *Manager) ParseClaimsUnsafe(tokenStr string) (*Claims, error)
• type Tenant
• type TokenKind

Functions

func HasTenantPermission

func HasTenantPermission(c Claims, tenantID string, perm common.Permission) bool

HasTenantPermission checks if the user has a specific permission in a tenant

func HasTenantRole

func HasTenantRole(c Claims, tenantID, role string) bool

HasTenantRole checks if the user has a specific role in a tenant

Types

type Claims

type Claims struct {
	Sub       string            `json:"sub"`
	Kind      TokenKind         `json:"typ"`
	Tenants   map[string]Tenant `json:"tenants,omitempty"`
	JTI       string            `json:"jti"`
	ExpiresAt *jwt.NumericDate  `json:"exp,omitempty"`
	IssuedAt  *jwt.NumericDate  `json:"iat,omitempty"`
	Issuer    string            `json:"iss,omitempty"`
	Audience  jwt.ClaimStrings  `json:"aud,omitempty"`
}

Claims defines our custom JWT payload

func (Claims) GetAudience

func (c Claims) GetAudience() (jwt.ClaimStrings, error)

func (Claims) GetExpirationTime

func (c Claims) GetExpirationTime() (*jwt.NumericDate, error)

func (Claims) GetIssuedAt

func (c Claims) GetIssuedAt() (*jwt.NumericDate, error)

func (Claims) GetIssuer

func (c Claims) GetIssuer() (string, error)

func (Claims) GetNotBefore

func (c Claims) GetNotBefore() (*jwt.NumericDate, error)

func (Claims) GetSubject

func (c Claims) GetSubject() (string, error)

type Config

type Config struct {
	Prefix     string        `json:"prefix"`
	Secret     string        `json:"secret"`
	Issuer     string        `json:"issuer"`
	AccessTTL  time.Duration `json:"access_ttl"`
	RefreshTTL time.Duration `json:"refresh_ttl"`
	PurposeTTL time.Duration `json:"purpose_ttl"`
}

type Manager

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

func NewManager

func NewManager(config Config) (*Manager, error)

NewManager creates a JWT manager with defaults

func (*Manager) IssueAccessToken

func (m *Manager) IssueAccessToken(sub string, tenants map[string]Tenant, extra map[string]any) (string, *Claims, error)

IssueAccessToken Public issue methods

func (*Manager) IssuePurposeToken

func (m *Manager) IssuePurposeToken(sub string, tenants map[string]Tenant, extra map[string]any) (string, *Claims, error)

func (*Manager) IssueRefreshToken

func (m *Manager) IssueRefreshToken(sub string, tenants map[string]Tenant, extra map[string]any) (string, *Claims, error)

func (*Manager) IssueToken

func (m *Manager) IssueToken(sub string, kind TokenKind, tenants map[string]Tenant, extra map[string]any, ttl time.Duration) (string, error)

IssueToken Generic issue with custom TTL

func (*Manager) ParseClaims

func (m *Manager) ParseClaims(tokenStr string) (*Claims, error)

ParseClaims validates signature and returns Claims

func (*Manager) ParseClaimsUnsafe

func (m *Manager) ParseClaimsUnsafe(tokenStr string) (*Claims, error)

ParseClaimsUnsafe parses without signature validation

type Tenant

type Tenant struct {
	Role        string              `json:"role"`
	Tenant      string              `json:"tenant"`
	Permissions []common.Permission `json:"permissions"`
}

Tenant holds role + permissions for a specific tenant

type TokenKind

type TokenKind string

const (
	AccessToken  TokenKind = "access"
	RefreshToken TokenKind = "refresh"
	PurposeToken TokenKind = "purpose"
)