|
2 years ago | |
---|---|---|
badges | 2 years ago | |
jws | 2 years ago | |
jwt | 2 years ago | |
opinionated | 2 years ago | |
strictjson | 2 years ago | |
.gitignore | 2 years ago | |
LICENSE.txt | 2 years ago | |
README.md | 2 years ago | |
RELEASES.md | 2 years ago | |
authority.go | 2 years ago | |
generate-test-jwt.py | 2 years ago | |
go.mod | 2 years ago | |
go.sum | 2 years ago |
README.md
KISStokens
A Library for Signing, Verifying and Decoding JWS/JWT Authentication Tokens
Summary
KISStokens is a Go library for signing, verifying and decoding authentication tokens following the JSON Web Signature (JWS, RFC7515) and JSON Web Token (JWT, RFC7519) standards.
KISStokens offers both a high-level and a low-level API. While the high-level API aims to be easily usable from within applications, offering implementations with reasonable defaults for common use cases, the low-level API offers a more direct representation of the JWS and JWT standards, for use cases in which more control is needed.
Status
KISStokens is currently in the 0.x version range.
It can be used for experimental and testing purposes. Although this library is built with robustness and security in mind, its use in production is expressly discouraged until v1.0.0.
Make sure you have read and understood the library's license (see LICENCE file), especially the sections "Disclaimer of Warranty" and "Limitation of Liability", before using the library.
Usage
Reference Documentation
Reference documentation can be found at pkg.go.dev
Installation
Install KISStokens by running the following:
go get codeberg.org/lhinderberger/KISStokens
High-Level API
For common use cases, it is recommended to use the opinionated high-level API,
which can be found in the opinionated
sub-package.
Import is using:
import "codeberg.org/lhinderberger/KISStokens/opinionated"
Then build a token authority, an object holding key and configuration for signing and verifying authentication tokens, like this:
authority, err := opinionated.NewTokenAuthority(secretKey)
Using the token authority, you can then sign tokens like this:
encodedToken, err := authority.Sign(&claims) // With claims being an jwt.Claims struct
Or decode and verify a token like this:
claims, err := authority.DecodeAndVerify(token)
Low-level API
While the high-level API provides an easy interface and reasonable defaults for common use cases, there are times when you need more control about your tokens.
For this, KISStokens exposes a low-level API in its jws
and jwt
packages.
These packages map fairly closely to the relevant parts of the RFC7515 and
RFC7519 standards. They for example allow you to precisely control the contents
of your JWS tokens and to manipulate the JOSE Header.
For details about the low-level API, pleae refer to the reference documentation at pkg.go.dev.
Dependencies
KISStokens is designed to have no run-time dependencies, other than Go's standard library.
Thus, the dependencies in go.mod
/ go.sum
are testing dependencies
and can be omitted when redistributing an application that uses KISStokens.
Versioning and Compatibility
Versioning of KISStokens follows the Semantic Versioning convention.
KISStokens keeps a changelog in RELEASES.md
Until 1.0.0, any substantial changes to the library (breaking and non-breaking) will trigger an increase of the minor version, while bug fixes and similar minor improvements may trigger an increase of the patch version.
Copyright
KISStokens is (C) 2021 Lucas Hinderberger
It is licensed under the Apache Licence Version 2.0. For details, please refer to the LICENCE file.
Contact
The repository of KISStokens can be found at https://codeberg.org/lhinderberger/KISStokens
You're welcome to file bug reports, other issues and pull requests there.
You can also contact the author via email at mail@lhinderberger.com