jwthelper

package module
v0.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 13, 2021 License: MIT Imports: 15 Imported by: 0

README

jwthelper

jwt标准过于简单,往往在生产上并不是简单使用,本项目基于我的这篇博文.在可以进行简单签名简单验签的同时也支持使用伴生的刷新jwt做自动刷新令牌.

本项目本质上只是github.com/golang-jwt/jwt/v4的封装,只是提供了相对更友好的接口和一些专用模式封装而已

特性

  • 有Signer类用于作为签名器
  • 有Verifier类用于做签名校验器
  • 提供Meta函数用于查看签名器和签名校验器的元信息
  • 提供接口UniversalJwtSigner和UniversalJwtVerifier方便抽象
  • 支持主流的RS256,RS384,RS512,ES256,ES384,ES512,HS256,HS384,HS5129种算法用于签名和校验
  • 支持构造jwt时同时创建伴生的刷新jwt,同时也支持校验这种token
  • 使用类似grpc的函数接口风格构造可选参数,提供丰富的可选项

用法

简单签名和验签

```golang
//签名,默认使用HS256算法,jti使用uuid4生成可以配置改为sonyflake或者自己实现一个满足接口`utils/idgener.IDGen`的id生成器
signer, err := NewSigner()
if err != nil {
    return err
}
payload := testPayLoad{
    A: 1,
    B: "B",
    C: 1.2,
}
//签名时可以添加sub等信息
token, err := signer.Sign(payload, signoptions.WithSub("test"),signoptions.WithAud("testaud"))

//验签,默认使用HS256算法
verifier, err := NewVerifier(WithDefaultAUD("testaud"), WithDefaultISSRange(signer.Meta().Iss))
if err != nil {
    return err
}
payload1 := testPayLoad{}
//可以校验iss,aud和sub等
jti, timeleft, err := verifier.Verify(token, &payload1,veriffyoptions.WithSUBMustBe(test))
if err == nil {
    return err
}
```

带fresh_token的签名和对应验签

```golang
//签名
signer, err := NewSigner()
if err != nil {
    return err
}
payload := testPayLoad{
    A: 1,
    B: "B",
    C: 1.2,
}
//签名的不同之处只是增加了选项`signoptions.WithRefreshTTL`
token, err := signer.Sign(payload, signoptions.WithSub("test"),signoptions.WithAud("testaud"),signoptions.WithRefreshTTL(time.Hour*24))

//验签
verifier, err := NewVerifier(WithDefaultAUD("testaud"), WithDefaultISSRange(signer.Meta().Iss))
if err != nil {
    return err
}
payload1 := testPayLoad{}
//会根据token中`RefreshToken`字段是否为空值来确定是简单jwt还是带伴生fresh_tokende的
jti, timeleft, err := verifier.Verify(token, &payload1,veriffyoptions.WithSUBMustBe(test))
if err == nil {
    return err
}
```

更多的方法可选项可以看文档

附加工具

cmd目录用于构造jwthelper的命令行工具,这个工具提供如下工具:

  • jwthelper createkey用于创建公私钥对
  • jwthelper signer,用于启动一个基于grpc的签名器服务端,具体接口请查看pbschema/jwtsigner.proto
  • jwthelper verifier,用于启动一个基于grpc的签名校验器服务端,具体接口请查看pbschema/jwtverifier.proto

这个工具也可以使用docker使用,托管在dockerhub上的hsz1273327/jwthelper下

附加模块

  • utils/idgener模块提供两个IDGen接口的实现分别是

    • UUID4Gen,使用uuid4生成全局唯一id
    • SonyflakeGen,使用github.com/sony/sonyflake生成全局唯一id

  • utils/machineid模块用于通过本机的第一张网卡的ip生成机器id

  • utils/keygener模块用于生成随机的公私钥对

  • proxy用于代理满足UniversalJwtSigner和UniversalJwtVerifier接口的对象

  • sdk用于对接cmd中提供的grpc,使用它构造的对象也分别满足UniversalJwtSigner和UniversalJwtVerifier接口

  • gin_middlewaregin的校验模块工具

Documentation

Overview

jwthelper 定义该项目下的各种对象接口

verifier jwt校验器

Index

Constants

This section is empty.

Variables

View Source 
var DefaultSignerOptions = SignerOptions{
	Algo:       jwt_pb.EncryptionAlgorithm_HS256,
	Iss:        fmt.Sprintf("%s-%s", machineid.GetMachineID(), jwt_pb.EncryptionAlgorithm_HS256.String()),
	DefaultTTL: time.Minute * 10,
	JtiGen:     &idgener.UUID4Gen{},
	Key:        []byte("a secret"),
}
View Source 
var DefaultVerifierOptions = VerifierOptions{
	Algo:            jwt_pb.EncryptionAlgorithm_HS256,
	Key:             []byte("a secret"),
	DefaultISSRange: []string{},
}

Functions

This section is empty.

Types

type Signer 

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

func NewSigner 

func NewSigner(opts ...SignerOption) (*Signer, error)

NewSigner 创建一个签名器对象

func (*Signer) Meta 

func (signer *Signer) Meta() (*jwt_pb.SignerMeta, error)

Meta 获取签名器元数据

func (*Signer) Sign 

func (signer *Signer) Sign(payload interface{}, opts ...signoptions.SignOption) (*jwt_pb.Token, error)

Sign 签名一个token @Params payload interface{} 负载对象,需要是可以用json解析的对象 @Params opts ...signoptions.SignOption 签名的设置项,详见signoptions模块 @Returns *jwt_pb.Token jwt的token对象,其中AccessToken是jwt主体token,如果成功一定会有,如果设置了`WithRefreshExpAt`或者`WithRefreshTTL`则会创建一个伴生的RefreshToken用于自动刷新

type SignerOption 

type SignerOption interface {
	Apply(*SignerOptions)
}

func WithDefaultEffectiveInterval 

func WithDefaultEffectiveInterval(defaultEffectiveInterval time.Duration) SignerOption

WithDefaultEffectiveInterval 签名器的创建参数,设置jwt签发者所谓默认令牌开始生效间隔

func WithDefaultTTL 

func WithDefaultTTL(defaultTTL time.Duration) SignerOption

WithDefaultTTL 签名器的创建参数,设置jwt签发者的默认令牌存在时长,注意过期时间为开始生效时间+令牌存在时长

func WithPemPrivateKey 

func WithPemPrivateKey(keybytes []byte) SignerOption

WithPemPrivateKey 签名器的创建参数,非对称加密设置以pem格式保存的私钥

func WithPemPrivateKeyFromFile 

func WithPemPrivateKeyFromFile(keyPath string) SignerOption

WithPemPrivateKeyFromFile 签名器的创建参数,非对称加密设置以pem格式保存的私钥

func WithSignAlgo 

func WithSignAlgo(algo jwt_pb.EncryptionAlgorithm) SignerOption

WithSignAlgo 签名器的创建参数,设置jwt签发id生成器,如果Iss以机器ID开头则会任务Iss是默认格式,会更新默认Iss的后半段为算法名

func WithSignIss 

func WithSignIss(iss string) SignerOption

WithSignIss 签名器的创建参数,设置jwt签发者标识

func WithSignJtiGen 

func WithSignJtiGen(jtiGen idgener.IDGen) SignerOption

WithSignJtiGen 签名器的创建参数,设置jwt签发id生成器

func WithSignSecretKey 

func WithSignSecretKey(keybytes []byte) SignerOption

WithSignSecretKey 签名器的创建参数,对称加密设置密码

func WithSignSecretKeyFromFile 

func WithSignSecretKeyFromFile(keyPath string) SignerOption

WithSignSecretKeyFromFile 签名器的创建参数,对称加密从指定文件读取内容作为密码

type SignerOptions 

type SignerOptions struct {
	Algo                     jwt_pb.EncryptionAlgorithm
	Key                      []byte
	Iss                      string
	DefaultTTL               time.Duration //默认token超时
	DefaultEffectiveInterval time.Duration //默认token生效离签发时间间隔
	JtiGen                   idgener.IDGen //jti的生成器
}

签名器初始化选项

type UniversalJwtSigner 

type UniversalJwtSigner interface {
	//Meta 查看签名器元信息
	Meta() (*jwt_pb.SignerMeta, error)
	// Sign 签名一个token
	Sign(payload interface{}, opts ...signoptions.SignOption) (*jwt_pb.Token, error)
}

UniversalJwtSigner 通用jwt的签名器

type UniversalJwtVerifier 

type UniversalJwtVerifier interface {
	//Meta 查看签名器元信息
	Meta() (*jwt_pb.VerifierMeta, error)
	// 校验一个签名是否复合
	Verify(token *jwt_pb.Token, payload interface{}, opts ...verifyoptions.VerifyOption) (*jwt_pb.JwtStatus, error)
}

UniversalJwtVerifier 通用jwt的签名器

type Verifier 

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

func NewVerifier 

func NewVerifier(opts ...VerifierOption) (*Verifier, error)

NewVerifier 创建一个签名校验器对象

func (*Verifier) Meta 

func (verifier *Verifier) Meta() (*jwt_pb.VerifierMeta, error)

Meta 获取签名器元数据

func (*Verifier) Verify 

func (verifier *Verifier) Verify(token *jwt_pb.Token, payload interface{}, opts ...verifyoptions.VerifyOption) (*jwt_pb.JwtStatus, error)

* Verify 用Verifier对象验签

payload在有access且可以解析的情况下都会被解析出来 只有在access_token校验通过或者access_token超时但有refresh_token且refresh_token校验通过时才会有jwt_pb.JwtStatus的结果.

当access_token超时但有refresh_token且refresh_token校验通过时err为`exceptions.ErrValidationErrorExpired`

注意`refresh_token`的校验项包括

+ 是否可以解析为json + 是否包含`exp`字段 + `sub`字段是否存在 + `sub`字段是否和access_token中的一致 + 当不指定`WithNotCheckRefreshTokenJTI`时`jti`字段必须和access_token中的一致 + 当不指定`WithNotCheckRefreshTokenAUD`且access_token中有`aud`时则校验是否一致 + 当指定`WithIssMustIn`选项时校验`iss`是否在指定范围

@Params token jwt.Token 待校验的token @Params payload interface{} 校验出结果的用户负载写入的内容,注意只能是指针 @Params opts ...verifyoptions.VerifyOption @Returns *jwt_pb.JwtStatus jwt的状态信息,包括剩余时间,签发人,sub,aud等 @Returns error 各种验证失败的错误,注意当access_token过期但有refresh_token且refresh_token未过期时一样会报错exceptions.ErrValidationErrorExpired

type VerifierOption 

type VerifierOption interface {
	Apply(*VerifierOptions)
}

func WithDefaultAUD 

func WithDefaultAUD(aud string) VerifierOption

WithDefaultAUD 签名校验器的创建参数,设置解析器默认的aud

func WithDefaultISSRange 

func WithDefaultISSRange(iss ...string) VerifierOption

WithDefaultISSRange 签名校验器的创建参数,设置解析器默认的iss范围

func WithPemPublicKey 

func WithPemPublicKey(keybytes []byte) VerifierOption

WithPemPublicKey 签名校验器的创建参数,非对称加密设置以pem格式保存的公钥

func WithPemPublicKeyFromFile 

func WithPemPublicKeyFromFile(keyPath string) VerifierOption

WithPemPublicKeyFromFile 签名校验器的创建参数,非对称加密设置以pem格式保存的公钥

func WithVerifyAlgo 

func WithVerifyAlgo(algo jwt_pb.EncryptionAlgorithm) VerifierOption

WithVerifyAlgo 签名校验器的创建参数,设置jwt签发id生成器,如果Iss以机器ID开头则会任务Iss是默认格式,会更新默认Iss的后半段为算法名

func WithVerifySecretKey 

func WithVerifySecretKey(keybytes []byte) VerifierOption

WithVerifySecretKey 签名校验器的创建参数,对称加密的解密密码

func WithVerifySecretKeyFromFile 

func WithVerifySecretKeyFromFile(keyPath string) VerifierOption

WithVerifySecretKeyFromFile 签名校验器的创建参数,对称加密从指定文件读取内容作为密码

type VerifierOptions 

type VerifierOptions struct {
	Algo            jwt_pb.EncryptionAlgorithm
	DefaultAUD      string
	DefaultISSRange []string
	Key             []byte
}

签名校验器初始化选项

Source Files

View all Source files

Directories

Path Synopsis
cmd
createkey
jwtsigner_serv
jwtverifier_serv
exceptions 定义异常
 exceptions 定义异常
选项模块,Init函数的可选参数在这里定义 proxy 签名器和签名校验器的代理模块
 选项模块,Init函数的可选参数在这里定义 proxy 签名器和签名校验器的代理模块
signoptions 签名器签名方法的参数
 signoptions 签名器签名方法的参数
idgener
用于生成jwt的id
 用于生成jwt的id
keygener
machineid
用于生成MachineID,MachineID 当前机器的id,使用机器第一张网卡的可用ip地址构造
 用于生成MachineID,MachineID 当前机器的id,使用机器第一张网卡的可用ip地址构造
verifyoptions 签名校验器校验方法的参数
 verifyoptions 签名校验器校验方法的参数

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.