{"id":21275681,"url":"https://github.com/halimath/jose","last_synced_at":"2025-03-15T13:13:42.227Z","repository":{"id":57618105,"uuid":"387152915","full_name":"halimath/jose","owner":"halimath","description":"Idiomatic implementation of JWS/JWK/JWT for golang","archived":false,"fork":false,"pushed_at":"2024-05-05T14:09:27.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-22T03:27:31.019Z","etag":null,"topics":["go","golang","jwk","jws","jwt"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/halimath.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-18T10:53:49.000Z","updated_at":"2024-05-05T14:09:30.000Z","dependencies_parsed_at":"2024-11-21T09:46:16.780Z","dependency_job_id":null,"html_url":"https://github.com/halimath/jose","commit_stats":null,"previous_names":["halimath/jwx"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halimath%2Fjose","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halimath%2Fjose/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halimath%2Fjose/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halimath%2Fjose/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/halimath","download_url":"https://codeload.github.com/halimath/jose/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243732303,"owners_count":20338839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["go","golang","jwk","jws","jwt"],"created_at":"2024-11-21T09:36:09.138Z","updated_at":"2025-03-15T13:13:42.209Z","avatar_url":"https://github.com/halimath.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jose\n\nAn implementation of several _JSON Object Signature and Encryption_ (JOSE) specs for [Go](https://golang.org): JWS, JWK and JWT.\n\n![CI Status][ci-img-url] [![Go Report Card][go-report-card-img-url]][go-report-card-url] [![Package Doc][package-doc-img-url]][package-doc-url] [![Releases][release-img-url]][release-url]\n\nThis repo contains a module for the Golang programming language that provides an \nimplementation for JSON Web Signature (JWS; \n[RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)), JSON Web Keys (JWK;\n[RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517)) as well as JSON Web Tokens\n(JWT; [RFC7519](https://datatracker.ietf.org/doc/html/rfc7519)).\n\nThe module tries to provide an idiomatic Go API for creating, signing, decoding and verifying\nJSON Web Tokens and exporting cryptographic keys in JSON Web Key standard. While this module\ncontains packages named `jwk`, `jws` and `jwt` these packages do not strictly adhere to the\ncontent specified in the respective RFC. This is especially true for all the algorithms \ndefined in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518.html) - JSON Web Algorithms - \nwhich are in part implemented in this module.\n\n## Features\n\nThe following list summarizes the features provided by the this module.\n\n* JWS\n    * Sign and verify content using\n        * HS256\n        * HS384\n        * HS512\n        * RS256\n        * RS384\n        * RS512\n        * ES256\n        * ES384\n        * ES512\n* JWT\n    * Sign and verify tokens using the above signature methods\n    * Encode and decode claims standard claims\n    * Encode and decode custom claims\n    * Verify standard claims:\n        * Issuer\n        * Audience\n        * Expires\n        * Not before\n        * Max age\n\n## Installation\n\nUse `go get` to install the libary with your project. \n\n```\n$ go get github.com/halimath/jose\n```\n\nYou need Go \u003e= 1.18 to use the lib.\n\nThe production code has no other dependencies but the Go standard library. It uses \n`encoding/json` to do the marshaling/unmarshaling of JSON and uses several `crypto`\npackages. The only dependency declared in `go.mod` is the excellent\n[`github.com/go-test/deep`](https://github.com/go-test/deep) which is used in the\nunit tests.\n\n## Usage\n\n### JWT \u0026 JWS\n\nThe following code snippet shows how to create, sign, decode and verify a JWT using just\nthe standard claims of the spec. The example uses the `HS256` signature method which uses\nas single, symmetric key to both sign and verify. \n\n```go\nsig := jws.HS256([]byte(\"sh256-secret-key\"))\n\nclaims := jwt.StandardClaims{\n    ID:      \"17\",\n    Subject: \"john.doe\",\n    Issuer:  \"test\",\n    Audience: []string{\n        \"test\",\n        \"anotherTest\",\n    },\n    ExpirationTime: time.Now().Add(time.Hour).Unix(),\n}\n\ntoken, err := jwt.Sign(sig, claims)\nif err != nil {\n    panic(err)\n}\n\ntokenInCompactSerialization := token.Compact()\n\nfmt.Printf(\"JWT: %s\\n\", tokenInCompactSerialization)\n\ntokenDecoded, err := jwt.Decode(tokenInCompactSerialization)\nif err != nil {\n    panic(err)\n}\n\nif err := tokenDecoded.Verify(jwt.Signature(sig), jwt.ExpirationTime(time.Second)); err != nil {\n    panic(err)\n}\n```\n\nTo run the code you need to add the following imports along with all the standard import:\n\n```go\n\"github.com/halimath/jose/jws\"\n\"github.com/halimath/jose/jwt\"\n```\n\nA central type when using JWT is `jwt.Token`. A token is basically a `jws.JWS` which consists \nof a JOSE-header, a payload and a signature. In case of a `jwt.Token`, additional methods are\nprovided to interact with the payload which is known to be valid JSON. To create a `jwt.Token`\nyou can use one of the two functions:\n\n* `jwt.Sign` which creates a token by applying a signer to the claims\n* `jwt.Decode` which decodes a token from its _compact serialization_ which is the form most\n  people associate with a JWT: three base64 encoded strings separated by dots.\n\nNote that a decoded token is _not_ verified. This is a design intention which simplifies using\ntokens which are known to be valid and safe to use. Decoding simply makes sure, that the given\nstring contains a valid token in compact serialization.\n\nTo verify a token you use the `Verify` method and pass a list of verifiers to apply. A \n`jwt.Verifier` is an interface type with a single `Verify` method. The package contains\nimplementations for most of the standard claims as well as the signature. You can also\ncreate your own verifier and have them applied.\n\nThe following example shows how to create a token using custom claims and use a RSA key\npair to sign and verify the token.\n\n```go\nprivateKey, err := rsa.GenerateKey(rand.Reader, 2048)\nif err != nil {\n    panic(err)\n}\n\nsigner := jws.RS256Signer(privateKey)\n\ntype Claims struct {\n    jwt.StandardClaims\n    Fullname string `json:\"example.com/fullname\"`\n}\n\nclaims := Claims{\n    StandardClaims: jwt.StandardClaims{\n        ID:      \"17\",\n        Subject: \"john.doe\",\n        Issuer:  \"test\",\n        Audience: []string{\n            \"test\",\n            \"anotherTest\",\n        },\n        ExpirationTime: time.Now().Add(time.Hour).Unix(),\n    },\n    Fullname: \"John Doe\",\n}\n\ntoken, err := jwt.Sign(signer, claims)\nif err != nil {\n    panic(err)\n}\n\ntokenInCompactSerialization := token.Compact()\n\nfmt.Printf(\"JWT: %s\\n\", tokenInCompactSerialization)\n\ntoken2, err := jwt.Decode(tokenInCompactSerialization)\nif err != nil {\n    panic(err)\n}\n\nverifier := jws.RS256Verifier(\u0026privateKey.PublicKey)\n\nif err := token2.Verify(jwt.Signature(verifier), jwt.ExpirationTime(time.Second)); err != nil {\n    panic(err)\n}\n\nvar c Claims\nif err := token2.Claims(\u0026c); err != nil {\n    panic(err)\n}\n\nfmt.Printf(\"Full name: %s\\n\", c.Fullname)\n```\n\nNote that when using an asymmetric signature method (such as RSA or elliptic curves) you need\nto create a signer and a verifier, which are different values. When using a symmetric method,\na single value implements both steps.\n\nAlso note that the example creates a custom type `Claims` to hold the token's claims. While\nit is common that this type embeds `jwt.StandardClaims` it is not required. You can use \nwhatever type you want as claims, as long as it can be marshaled to JSON using \n`encoding/json`. \n\nTo unmarshal the token's payload into a custom claims value use the `token.Claims` method\nwhich uses `encoding/json` under the hood.\n\n## License\n\nCopyright 2021 Alexander Metzner\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n\n[ci-img-url]: https://github.com/halimath/jose/workflows/CI/badge.svg\n[go-report-card-img-url]: https://goreportcard.com/badge/github.com/halimath/jose\n[go-report-card-url]: https://goreportcard.com/report/github.com/halimath/jose\n[package-doc-img-url]: https://img.shields.io/badge/GoDoc-Reference-blue.svg\n[package-doc-url]: https://pkg.go.dev/github.com/halimath/jose\n[release-img-url]: https://img.shields.io/github/v/release/halimath/jose.svg\n[release-url]: https://github.com/halimath/jose/releases\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalimath%2Fjose","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalimath%2Fjose","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalimath%2Fjose/lists"}