mysession

README

JSON Web Token (JWT)原理

JSON Web Token (JWT)是一个开放标准(RFC 7519)，它定义了一种紧凑的、自包含的方式，用于作为JSON对象在各方之间安全地传输信息。该信息可以被验证和信任，因为它是数字签名的。

什么时候你应该用JSON Web Token

• Authorization (授权) : 这是使用JWT的最常见场景。一旦用户登录，后续每个请求都将包含JWT，允许用户访问该令牌允许的路由、服务和资源。单点登录（SingleSignOn，SSO）是现在广泛使用的JWT的一个特性，因为它的开销很小，并且可以轻松地跨域使用。
• Information Exchange (信息交换) : 对于安全的在各方之间传输信息而言，JSON Web Tokens无疑是一种很好的方式。因为JWT可以被签名，例如，用公钥/私钥对，你可以确定发送人就是它们所说的那个人。另外，由于签名是使用头和有效负载计算的，您还可以验证内容没有被篡改。

JSON Web Token的结构是什么样的

JSON Web Token由三部分组成，它们之间用圆点(.)连接。这三部分分别是：

# Header.Payload.Signature
Header
Payload
Signature

因此，一个典型的JWT看起来是这个样子的：

xxxxx.yyyyy.zzzzz

接下来，具体看一下每一部分：

Header，header典型的由两部分组成：token的类型（"JWT"）和算法名称（比如：HMAC，SHA256或者RSA等等）。

例如：

{
'alg': "HS256",
'typ': "JWT"
}

然后，用Base64对这个JSON编码就得到JWT的第一部分。

Payload，JWT的第二部分是payload，它包含声明（要求）。 声明是关于实体(通常是用户)和其他数据的声明。声明有三种类型: registered, public 和 private。

• Registered claims : 这里有一组预定义的声明，它们不是强制的，但是推荐。比如：iss (issuer), exp (expiration time), sub (subject), aud (audience)等。
• Public claims : 可以随意定义。
• Private claims : 用于在同意使用它们的各方之间共享信息，并且不是注册的或公开的声明。

下面是一个例子：

{
"sub": '1234567890',
"name": 'john',
"admin":true
}

然后，用Base64对这个JSON编码就得到JWT的第二部分。

注意，不要在JWT的payload或header中放置敏感信息，除非它们是加密的。

Signature，为了得到签名部分，你必须有编码过的header、编码过的payload、一个秘钥，签名算法是header中指定的那个，然对它们签名即可。

例如：

Signature = HMACSHA256(base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

签名是用于验证消息在传递过程中有没有被更改，并且，对于使用私钥签名的token，它还可以验证JWT的发送方是否为它所称的发送方。

示例：

JSON Web Tokens是如何工作的

在认证的时候，当用户用他们的凭证成功登录以后，一个JSON Web Token将会被返回。此后，token就是用户凭证了，你必须非常小心以防止出现安全问题。一般而言，你保存令牌的时候不应该超过你所需要它的时间。

无论何时用户想要访问受保护的路由或者资源的时候，用户代理（通常是浏览器）都应该带上JWT，典型的，通常放在Authorization header中，用Bearer schema。

header应该看起来是这样的：

Authorization: Bearer

Tokens存储在客户端。完全无状态，可扩展。我们的负载均衡器可以将用户传递到任意服务器，因为在任何地方都没有状态或会话信息。

JWT方式将用户状态分散到了客户端中，可以明显减轻服务端的内存压力。

服务器上的受保护的路由将会检查Authorization header中的JWT是否有效，如果有效，则用户可以访问受保护的资源。如果JWT包含足够多的必需的数据，那么就可以减少对某些操作的数据库查询的需要，尽管可能并不总是如此。

在任何地方都可以解码JWT的内容信息，你可以使用 https://jwt.io/#debugger-io 进行测试。

缺点

由于是无状态的，所以无法撤销 Token，只能被动过期。

解决： 改造成有状态的形式。

Documentation

Index

• Constants
• Variables
• func GenSigningPublicKey(jwtSigningPublicKey string) (publicKey *rsa.PublicKey, publicKeyError error)
• func NewError(t string, msg string) error
• type Data
• type Err
  • func (err *Err) Error() string
• type Interface

Constants

const (
	// JwtPayloadClientVersionName client jwtPayload version field
	JwtPayloadClientVersionName = "clientVersion"
	// JwtPayloadClientVersion client jwtPayload version value
	JwtPayloadClientVersion = 1.0
)

Variables

var (
	ErrUnauthorizedErrorType       = "ErrUnauthorizedError"
	ErrTryRefreshTokenErrorType    = "ErrTryRefreshTokenError"
	ErrTokenTheftDetectedErrorType = "ErrTokenTheftDetectedError"
	ErrUnKnowErrorType             = "ErrUnKnowError"

	// ErrUnauthorizedError access_token 不存在/被销毁，refresh_token刷新时格式不对
	ErrUnauthorizedError = NewError(ErrUnauthorizedErrorType, "unauthorized, your access token is invalid")
	// ErrTryRefreshTokenError access_token 过期/格式不对
	ErrTryRefreshTokenError = NewError(ErrTryRefreshTokenErrorType, "access token expired, try refresh token")
	// ErrTokenTheftDetectedError refresh_token 不存在/被销毁
	ErrTokenTheftDetectedError = NewError(ErrTokenTheftDetectedErrorType, "token theft detected, try re-log in")
	// ErrUnKnowErrorTypeError 未知错误
	ErrUnKnowErrorTypeError = NewError(ErrUnKnowErrorType, "un know err")
)

Functions

func GenSigningPublicKey

func GenSigningPublicKey(jwtSigningPublicKey string) (publicKey *rsa.PublicKey, publicKeyError error)

func NewError

func NewError(t string, msg string) error

Types

type Data

type Data struct {
	// 用户ID
	UserId string `json:"user_id,omitempty"`
	// 创建时间，毫秒
	CreateMSTime int64 `json:"create_ms_time,omitempty"`
	// 辅助
	CreateString string `json:"create_string,omitempty"`
	// 过期时间，毫秒
	ExpiryMSTime int64 `json:"expiry_ms_time,omitempty"`
	// 辅助
	ExpiryString string `json:"expiry_string,omitempty"`
	// 是否已过期
	IsExpire bool `json:"is_expire,omitempty"`
	// 服务端数据库令牌对ID，可忽视
	ServerTokenHandle string `json:"server_token_handle,omitempty"`
	// 客户端Payload数据，返回给客户端的数据，客户端解密可看
	ClientPayload map[string]interface{} `json:"client_payload,omitempty"`
	// 服务端Session数据，保存在服务器端的数据，客户端不可看
	ServerSessionData map[string]interface{} `json:"server_session_data,omitempty"`
}

Data 数据

type Err

type Err struct {
	Type string
	Msg  string
}

Err Diy Error

func (*Err) Error

func (err *Err) Error() string

type Interface

type Interface interface {
	// Config 配置令牌有效时间
	Config(refreshTokenExpireTime time.Duration, accessTokenExpireTime time.Duration)
	// CreateNewLogInToken 创建令牌对，可传入客户端或服务端数据
	CreateNewLogInToken(userId string, clientJwtPayload map[string]interface{}, serverSessionData map[string]interface{}) (accessToken, refreshToken string, err error)
	// GetSessionInfoByAccessToken 获取某令牌对信息，先走JWT无状态解码数据，force则强制查询服务端
	GetSessionInfoByAccessToken(accessToken string, force bool) (tokenData Data, err error)
	// GetAllSessionsForUser 获取某用户所有令牌对信息
	GetAllSessionsForUser(userId string) (sessionInfos []Data, err error)
	// RevokeLogInTokenByUserId 撤销某用户所有令牌对
	RevokeLogInTokenByUserId(userId string) error
	// RevokeLogInTokenByAccessToken 撤销用户某令牌对
	RevokeLogInTokenByAccessToken(accessToken string) (revoke bool, err error)
	// RefreshLogInToken 刷新令牌对
	RefreshLogInToken(refreshToken string) (newAccessToken string, newRefreshToken string, err error)
	// GetSignPublicKey 获取服务端签名key，客户端使用这个来进行解密，可以是空
	GetSignPublicKey() (publicKey string, err error)
	// ParseAccessToken 解析和验证JWT信息，客户端方法
	ParseAccessToken(accessToken string, publicKey string) (tokenData Data, err error)
}

Interface Session暴露接口