https://github.com/s12v/go-jwks
A Go library to retrieve RSA public keys from a JWKS (JSON Web Key Set) endpoint
https://github.com/s12v/go-jwks
jwk jwks jwt rsa
Last synced: 3 months ago
JSON representation
A Go library to retrieve RSA public keys from a JWKS (JSON Web Key Set) endpoint
- Host: GitHub
- URL: https://github.com/s12v/go-jwks
- Owner: s12v
- License: mit
- Created: 2018-07-20T21:41:27.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2023-05-08T12:56:40.000Z (over 2 years ago)
- Last Synced: 2025-04-09T18:09:01.947Z (6 months ago)
- Topics: jwk, jwks, jwt, rsa
- Language: Go
- Homepage:
- Size: 48.8 KB
- Stars: 42
- Watchers: 2
- Forks: 17
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.com/s12v/go-jwks)
[](https://codecov.io/gh/s12v/go-jwks)
# go-jwks
A Go library to retrieve RSA public keys from a JWKS (JSON Web Key Set) endpoint.
## Installation
Using [Go modules](https://github.com/golang/go/wiki/Modules)
```bash
go get github.com/s12v/go-jwks@v0.2.1
```
## Dependencies
* `github.com/square/go-jose` - JWT library
* `github.com/patrickmn/go-cache` - default in-memory cache
## Example
`GetEncryptionKey` returns `*jose.JSONWebKey` for a given key id:
```go
package main
import (
"log"
"time"
"github.com/s12v/go-jwks"
"github.com/square/go-jose"
)
func main() {
jwksSource := jwks.NewWebSource("https://www.googleapis.com/oauth2/v3/certs")
jwksClient := jwks.NewDefaultClient(
jwksSource,
time.Hour, // Refresh keys every 1 hour
12*time.Hour, // Expire keys after 12 hours
)
var jwk *jose.JSONWebKey
jwk, err := jwksClient.GetEncryptionKey("c6af7caa0895fd01e778dceaa7a7988347d8f25c")
if err != nil {
log.Fatal(err)
}
log.Printf("key: %v, alg: %v, use: %v", jwk.KeyID, jwk.Algorithm, jwk.Use)
}
```
Log:
```
2018/07/30 01:22:35 Fetchng JWKS from https://www.googleapis.com/oauth2/v3/certs
2018/07/30 01:22:36 key: c6af7caa0895fd01e778dceaa7a7988347d8f25c, alg: RS256, use: sig
```
## Caching
### Key refresh and TTL
There are two caching parameters:
- `refresh` - the key will be fetched from the source after this interval
- `ttl` - if not used, the key will be deleted from cache
On the first request, the key is synchronously fetched from the key server and stored in the cache.
On the next request after `refresh` interval, the key will be refreshed in the background (not affect response time).
Only 1 key refresh is executed at the same time.
If the key is not requested during `ttl` interval, it will be removed from cache.
## Cache implementations
Default cache is `github.com/patrickmn/go-cache` in-memory cache.
You can provide your own cache implementation, see `cache.go`:
```go
type Cache interface {
// Get an item from the cache and itsexpiration time.
// Returns the item or nil, and a bool indicating whether the key was found
GetWithExpiration(k string) (interface{}, time.Time, bool)
// Add an item to the cache, replacing any existing item.
Set(k string, x interface{})
}
```
and pass it to `func NewClient(...)`
## Source
Default source is `WebSource`. You can provide your own implementation, see `source.go`:
```go
type JWKSSource interface {
JSONWebKeySet() (*jose.JSONWebKeySet, error)
}
```