Skip to content

Commit c749c56

Browse files
Aakarsh133oxistoCopilot
authored
Add custom claims example via Struct (#8)
* Added an example with Custom Claims * Fixed intends and typos * Apply suggestions from code review Co-authored-by: Copilot <[email protected]> --------- Co-authored-by: Christian Banse <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 45db9cc commit c749c56

File tree

1 file changed

+40
-0
lines changed

1 file changed

+40
-0
lines changed

docs/usage/create.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,46 @@ s = t.SignedString(key) // (6)!
9292
[^iss]: [Section 4.1.1 of RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1)
9393
[^sub]: [Section 4.1.2 of RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.2)
9494

95+
## With Custom Claims
96+
97+
In the above examples Custom Claims have been used with [`jwt.MapClaims`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#MapClaims) type. However, when working with a consistent structure across multiple tokens, it's often cleaner and more maintainable to define your own struct type embedding jwt.RegisteredClaims. This allows for type safety and easier reusablility.
98+
99+
```go
100+
var (
101+
key *ecdsa.PrivateKey
102+
t *jwt.Token
103+
s string
104+
claims CustomClaims
105+
)
106+
107+
type CustomClaims struct {
108+
Foo string `json:"foo"`
109+
jwt.RegisteredClaims
110+
}
111+
112+
claims := CustomClaims{ // (1)!
113+
Foo: "bar", // (2) !
114+
RegisteredClaims: jwt.RegisteredClaims{ // (3) !
115+
ExpiresAt: jwt.NewNumericDate(time.Now().Add(24 * time.Hour)), // (4) !
116+
Issuer: "john", // (5) !
117+
Subject: "subject", // (6) !
118+
},
119+
}
120+
121+
key = /* Load key from somewhere, for example a file */
122+
123+
t = jwt.NewWithClaims(jwt.SigningMethodES256, claims) // (7)!
124+
s = t.SignedString(key) // (8)!
125+
```
126+
1. This initializes claims variable based of the type CustomClaims struct as declared. This will have all definitions and values for the custom claims along with the registered claim values embedded via[`jwt.RegisteredClaims`] (https://datatracker.ietf.org/doc/html/rfc7519#section-4.1).
127+
2. The "bar" string here is the actual value for the custom claim Foo. This is completely user-defined and not governed by any JWT standardization, allowing for flexible claim modeling across tokens.
128+
3. jwt.RegisteredClaims{...} sets standard claims that are recognized across JWT-compliant systems. This may include expiry, issuer, and subject identifiers.
129+
4. The ExpiresAt field uses jwt.NewNumericDate(...) to convert a Go time.Time into the numeric timestamp format expected in JWTs. Here, the token is valid for 24 hours.
130+
5. The `"john"` value assigned to the Issuer[^iss] claim helps the recipient validate who issued the token — a critical aspect when tokens are exchanged across systems.
131+
6. The `"subject"` value assigned to Subject[^sub] identifies the principal for whom the token was issued, often corresponding to the authenticated user.
132+
7. This initializes a new [`jwt.Token`](https://pkg.go.dev/github.com/golang-jwt/jwt/v5#Token) struct based on the supplied signing method. Here as well an **asymmetric** method is chosen, as the first parameter.
133+
8. This step computes a cryptographic signature based on the supplied private key.
134+
95135
## With Options
96136

97137
While we already prepared a

0 commit comments

Comments
 (0)