Repository files navigation

Ago (or 'golang' for search engine friendliness)implementation ofJSON WebTokens.

Starting withv4.0.0this project adds Go module support, but maintains backward compatibility witholderv3.x.y tags and upstreamgithub.com/dgrijalva/jwt-go. See theMIGRATION_GUIDE.md for more information. Versionv5.0.0 introduces major improvements to the validation of tokens, but is notentirely backward compatible.

After the original author of the library suggested migrating the maintenanceofjwt-go, a dedicated team of open source maintainers decided to clone theexisting library into this repository. Seedgrijalva/jwt-go#462 for adetailed discussion on this topic.

SECURITY NOTICE: Some older versions of Go have a security issue in thecrypto/elliptic. The recommendation is to upgrade to at least 1.15 See issuedgrijalva/jwt-go#216 for moredetail.

SECURITY NOTICE: It's important that youvalidate thealg presented iswhat youexpect.This library attempts to make it easy to do the right thing by requiring keytypes to match the expected alg, but you should take the extra step to verify it inyour usage. See the examples provided.

Our support of Go versions is aligned with Go'sversion releasepolicy. So we will support a majorversion of Go until there are two newer major releases. We no longer supportbuilding jwt-go with unsupported Go versions, as these contain securityvulnerabilities that will not be fixed.

JWT.io hasa great introduction to JSON WebTokens.

In short, it's a signed JSON object that does something useful (for example,authentication). It's commonly used forBearer tokens in Oauth 2. A token ismade of three parts, separated by.'s. The first two parts are JSON objects,that have beenbase64urlencoded. The last part is the signature, encoded the same way.

The first part is called the header. It contains the necessary information forverifying the last part, the signature. For example, which encryption methodwas used for signing and what key was used.

The part in the middle is the interesting bit. It's called the Claims andcontains the actual stuff you care about. Refer toRFC7519 for information aboutreserved keys and the proper way to add your own.

This library supports the parsing and verification as well as the generation andsigning of JWTs. Current supported signing algorithms are HMAC SHA, RSA,RSA-PSS, and ECDSA, though hooks are present for adding your own.

1. To install the jwt package, you first need to haveGo installed, then you can use the commandbelow to addjwt-go as a dependency in your Go program.

go get -u github.com/golang-jwt/jwt/v5

2. Import it in your code:

import"github.com/golang-jwt/jwt/v5"

A detailed usage guide, including how to sign and verify tokens can be found onourdocumentation website.

Seethe project documentationfor examples of usage:

• Simple example of parsing and validating atoken
• Simple example of building and signing atoken
• Directory ofExamples

This library was last reviewed to comply withRFC7519 dated May 2015 with a fewnotable differences:

• In order to protect against accidental use ofUnsecuredJWTs, tokens usingalg=none will only be accepted if the constantjwt.UnsafeAllowNoneSignatureType is provided as the key.

This library is considered production ready. Feedback and feature requests areappreciated. The API should be considered stable. There should be very fewbackward-incompatible changes outside of major version updates (and only withgood reason).

This project usesSemantic Versioning 2.0.0. Accepted pullrequests will land onmain. Periodically, versions will be tagged frommain. You can find all the releases onthe project releasespage.

BREAKING CHANGES: A full list of breaking changes is available inVERSION_HISTORY.md. SeeMIGRATION_GUIDE.md for more information on updatingyour code.

This library publishes all the necessary components for adding your own signingmethods or key functions. Simply implement theSigningMethod interface andregister a factory method usingRegisterSigningMethod or provide ajwt.Keyfunc.

A common use case would be integrating with different 3rd party signatureproviders, like key management services from various cloud providers or HardwareSecurity Modules (HSMs) or to implement additional standards.

Disclaimer: Unless otherwise specified, these integrations are maintained bythird parties and should not be considered as a primary offer by any of thementioned cloud providers

Go package documentation can be foundonpkg.go.dev. Additionaldocumentation can be found onour projectpage.

The command line utility included in this project (cmd/jwt) provides astraightforward example of token creation and parsing as well as a useful toolfor debugging your own integration. You'll also find several implementationexamples in the documentation.

golang-jwt incorporates a modified versionof the JWT logo, which is distributed under the terms of theMITLicense.