|
| 1 | +# Creating a New JWT |
| 2 | + |
| 3 | +One of the primary goals of this library is to create a new JWT (or in short |
| 4 | +*token*). |
| 5 | + |
| 6 | +## With Default Options |
| 7 | + |
| 8 | + The easiest way to create a token is to use the |
| 9 | +[`jwt.New`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#New) function. It |
| 10 | +then needs one of the available [signing methods](./signing_methods.md), to |
| 11 | +finally sign and convert the token into a string format (using the |
| 12 | +[`SignedString`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#Token.SignedString) |
| 13 | +method). In the first example, we are using a **symmetric** signing method, i.e., |
| 14 | +HS256. For a symmetric method, both the signing and the verifying key are the |
| 15 | +same and thus, both must be equally protected (and should definitely NOT be |
| 16 | +stored in your code). |
| 17 | + |
| 18 | +```go |
| 19 | +var ( |
| 20 | + key []byte |
| 21 | + t *jwt.Token |
| 22 | + s string |
| 23 | +) |
| 24 | + |
| 25 | +key = /* Load key from somewhere, for example an environment variable */ |
| 26 | +t = jwt.New(jwt.SigningMethodHS256) // (1)! |
| 27 | +s = t.SignedString(key) // (2)! |
| 28 | +``` |
| 29 | + |
| 30 | +1. This initializes a new |
| 31 | + [`jwt.Token`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#Token) struct |
| 32 | + based on the supplied signing method. In this case a **symmetric** method is |
| 33 | + chosen. |
| 34 | +2. This step computes a cryptographic signature based on the supplied key. |
| 35 | + |
| 36 | +Signing using an *asymmetric* signing method (for example ECDSA) works quite |
| 37 | +similar. For an **asymmetric** method, the private key (which must be kept |
| 38 | +secret) is used to *sign* and the corresponding public key (which can be freely |
| 39 | +transmitted) is used to *verify* the token. |
| 40 | + |
| 41 | +```go |
| 42 | +var ( |
| 43 | + key *ecdsa.PrivateKey |
| 44 | + t *jwt.Token |
| 45 | + s string |
| 46 | +) |
| 47 | + |
| 48 | +key = /* Load key from somewhere, for example a file */ |
| 49 | +t = jwt.New(jwt.SigningMethodES256) // (1)! |
| 50 | +s = t.SignedString(key) // (2)! |
| 51 | +``` |
| 52 | + |
| 53 | +1. This initializes a new [`jwt.Token`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#Token) struct based on the supplied signing method. In this case a **asymmetric** method is chosen. |
| 54 | +2. This step computes a cryptographic signature based on the supplied private |
| 55 | + key. |
| 56 | + |
| 57 | +Note, that the chosen signing method and the type of key must match. Please refer to [Signing Methods](./signing_methods.md) for a complete overview. |
| 58 | + |
| 59 | + |
| 60 | +## With Additional Claims |
| 61 | + |
| 62 | +## With Options |
| 63 | + |
| 64 | +While we already prepared a |
| 65 | +[`jwt.TokenOption`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#TokenOption) |
| 66 | +type, which can be supplied as a varargs to |
| 67 | +[`jwt.New`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#New) and |
| 68 | +[`jwt.NewWithClaims`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#NewWithClaims), |
| 69 | +these are strictly for future compatibility and are currently not used. |
0 commit comments