Skip to content

Commit ddea2b1

Browse files
anakinjanakinj
authored
Improve readme algorithm examples (#687)
* Add expcility irb * Fix algo examples * Try to tame the MD * A bit space * Add irb dependency to gemspec
1 parent cbbdf17 commit ddea2b1

File tree

3 files changed

+62
-101
lines changed

3 files changed

+62
-101
lines changed

‎README.md‎

Lines changed: 60 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,13 @@ A ruby implementation of the [RFC 7519 OAuth JSON Web Token (JWT)](https://tools
99

1010
If you have further questions related to development or usage, join us: [ruby-jwt google group](https://groups.google.com/forum/#!forum/ruby-jwt).
1111

12-
See [CHANGELOG.md](CHANGELOG.md) for a complete set of changes.
13-
14-
## Upcoming breaking changes
15-
16-
Check out breaking changes in the upcoming **version 3.0** from the [upgrade guide](UPGRADING.md)
12+
See [CHANGELOG.md](CHANGELOG.md) for a complete set of changes and [upgrade guide](UPGRADING.md) for upgrading between major versions.
1713

1814
## Sponsors
1915

20-
| Logo | Message |
21-
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
22-
| ![auth0 logo](https://user-images.githubusercontent.com/83319/31722733-de95bbde-b3ea-11e7-96bf-4f4e8f915588.png) | If you want to quickly add secure token-based authentication to Ruby projects, feel free to check Auth0's Ruby SDK and free plan at [auth0.com/developers](https://auth0.com/developers?utm_source=GHsponsor&utm_medium=GHsponsor&utm_campaign=rubyjwt&utm_content=auth) |
16+
|Logo|Message|
17+
|----|-------|
18+
|![auth0 logo](https://user-images.githubusercontent.com/83319/31722733-de95bbde-b3ea-11e7-96bf-4f4e8f915588.png)|If you want to quickly add secure token-based authentication to Ruby projects, feel free to check Auth0's Ruby SDK and free plan at [auth0.com/developers](https://auth0.com/developers?utm_source=GHsponsor&utm_medium=GHsponsor&utm_campaign=rubyjwt&utm_content=auth)|
2319

2420
## Installing
2521

@@ -60,24 +56,15 @@ See [JSON Web Algorithms (JWA) 3.1. "alg" (Algorithm) Header Parameter Values fo
6056
- none - unsigned token
6157

6258
```ruby
63-
6459
payload = { data: 'test' }
60+
token = JWT.encode(payload, nil, 'none')
61+
# => "eyJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9."
6562

66-
# IMPORTANT: set nil as password parameter
67-
token = JWT.encode(payload, nil, 'none')
68-
69-
# eyJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9.
70-
puts token
71-
72-
# Set password to nil and validation to false otherwise this won't work
73-
decoded_token = JWT.decode(token, nil, false)
74-
75-
# Array
76-
# [
77-
# {"data"=>"test"}, # payload
78-
# {"alg"=>"none"} # header
79-
# ]
80-
puts decoded_token
63+
decoded_token = JWT.decode(token, nil, true, { algorithm: 'none' })
64+
# => [
65+
# {"data"=>"test"}, # payload
66+
# {"alg"=>"none"} # header
67+
# ]
8168
```
8269

8370
### **HMAC**
@@ -87,22 +74,17 @@ puts decoded_token
8774
- HS512 - HMAC using SHA-512 hash algorithm
8875

8976
```ruby
90-
# The secret must be a string. With OpenSSL 3.0/openssl gem `<3.0.1`, JWT::DecodeError will be raised if it isn't provided.
77+
payload = { data: 'test' }
9178
hmac_secret = 'my$ecretK3y'
9279

9380
token = JWT.encode(payload, hmac_secret, 'HS256')
94-
95-
# eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.pNIWIL34Jo13LViZAJACzK6Yf0qnvT_BuwOxiMCPE-Y
96-
puts token
81+
# => "eyJhbGciOiJIUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.pNIWIL34Jo13LViZAJACzK6Yf0qnvT_BuwOxiMCPE-Y"
9782

9883
decoded_token = JWT.decode(token, hmac_secret, true, { algorithm: 'HS256' })
99-
100-
# Array
101-
# [
102-
# {"data"=>"test"}, # payload
103-
# {"alg"=>"HS256"} # header
104-
# ]
105-
puts decoded_token
84+
# => [
85+
# {"data"=>"test"}, # payload
86+
# {"alg"=>"HS256"} # header
87+
# ]
10688
```
10789

10890
### **RSA**
@@ -112,22 +94,18 @@ puts decoded_token
11294
- RS512 - RSA using SHA-512 hash algorithm
11395

11496
```ruby
97+
payload = { data: 'test' }
11598
rsa_private = OpenSSL::PKey::RSA.generate(2048)
116-
rsa_public = rsa_private.public_key
99+
rsa_public = rsa_private.public_key
117100

118101
token = JWT.encode(payload, rsa_private, 'RS256')
119-
120-
# eyJhbGciOiJSUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.GplO4w1spRgvEJQ3-FOtZr-uC8L45Jt7SN0J4woBnEXG_OZBSNcZjAJWpjadVYEe2ev3oUBFDYM1N_-0BTVeFGGYvMewu8E6aMjSZvOpf1cZBew-Vt4poSq7goG2YRI_zNPt3af2lkPqXD796IKC5URrEvcgF5xFQ-6h07XRDpSRx1ECrNsUOt7UM3l1IB4doY11GzwQA5sHDTmUZ0-kBT76ZMf12Srg_N3hZwphxBtudYtN5VGZn420sVrQMdPE_7Ni3EiWT88j7WCr1xrF60l8sZT3yKCVleG7D2BEXacTntB7GktBv4Xo8OKnpwpqTpIlC05dMowMkz3rEAAYbQ
121-
puts token
102+
# => "eyJhbGciOiJSUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.CCkO35qFPijW8Gwhbt8a80PB9fc9FJ19hCMnXSgoDF6Mlvlt0A4G-ah..."
122103

123104
decoded_token = JWT.decode(token, rsa_public, true, { algorithm: 'RS256' })
124-
125-
# Array
126-
# [
127-
# {"data"=>"test"}, # payload
128-
# {"alg"=>"RS256"} # header
129-
# ]
130-
puts decoded_token
105+
# => [
106+
# {"data"=>"test"}, # payload
107+
# {"alg"=>"RS256"} # header
108+
# ]
131109
```
132110

133111
### **ECDSA**
@@ -138,26 +116,22 @@ puts decoded_token
138116
- ES256K - ECDSA using P-256K and SHA-256
139117

140118
```ruby
119+
payload = { data: 'test' }
141120
ecdsa_key = OpenSSL::PKey::EC.generate('prime256v1')
142121

143122
token = JWT.encode(payload, ecdsa_key, 'ES256')
144-
145-
# eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg
146-
puts token
123+
# => "eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg"
147124

148125
decoded_token = JWT.decode(token, ecdsa_key, true, { algorithm: 'ES256' })
149-
150-
# Array
151-
# [
152-
# {"test"=>"data"}, # payload
153-
# {"alg"=>"ES256"} # header
154-
# ]
155-
puts decoded_token
126+
# => [
127+
# {"test"=>"data"}, # payload
128+
# {"alg"=>"ES256"} # header
129+
# ]
156130
```
157131

158132
### **EdDSA**
159133

160-
This algorithm has since version 3.0 been moved to the [jwt-eddsa gem](https://rubygems.org/gems/jwt-eddsa).
134+
Since version 3.0, the EdDSA algorithm has been moved to the [jwt-eddsa gem](https://rubygems.org/gems/jwt-eddsa).
161135

162136
### **RSASSA-PSS**
163137

@@ -166,22 +140,18 @@ This algorithm has since version 3.0 been moved to the [jwt-eddsa gem](https://r
166140
- PS512 - RSASSA-PSS using SHA-512 hash algorithm
167141

168142
```ruby
143+
payload = { data: 'test' }
169144
rsa_private = OpenSSL::PKey::RSA.generate(2048)
170-
rsa_public = rsa_private.public_key
145+
rsa_public = rsa_private.public_key
171146

172147
token = JWT.encode(payload, rsa_private, 'PS256')
173-
174-
# eyJhbGciOiJQUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.KEmqagMUHM-NcmXo6818ZazVTIAkn9qU9KQFT1c5Iq91n0KRpAI84jj4ZCdkysDlWokFs3Dmn4MhcXP03oJKLFgnoPL40_Wgg9iFr0jnIVvnMUp1kp2RFUbL0jqExGTRA3LdAhuvw6ZByGD1bkcWjDXygjQw-hxILrT1bENjdr0JhFd-cB0-ps5SB0mwhFNcUw-OM3Uu30B1-mlFaelUY8jHJYKwLTZPNxHzndt8RGXF8iZLp7dGb06HSCKMcVzhASGMH4ZdFystRe2hh31cwcvnl-Eo_D4cdwmpN3Abhk_8rkxawQJR3duh8HNKc4AyFPo7SabEaSu2gLnLfN3yfg
175-
puts token
148+
# => "eyJhbGciOiJQUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.BRWizdUjD5zAWw-EDBcrl3dDpQDAePz9Ol3XKC43SggU47G8OWwveA_..."
176149

177150
decoded_token = JWT.decode(token, rsa_public, true, { algorithm: 'PS256' })
178-
179-
# Array
180-
# [
181-
# {"data"=>"test"}, # payload
182-
# {"alg"=>"PS256"} # header
183-
# ]
184-
puts decoded_token
151+
# => [
152+
# {"data"=>"test"}, # payload
153+
# {"alg"=>"PS256"} # header
154+
# ]
185155
```
186156

187157
### **Custom algorithms**
@@ -210,8 +180,15 @@ module CustomHS512Algorithm
210180
end
211181
end
212182

213-
token = ::JWT.encode({'pay' => 'load'}, 'secret', CustomHS512Algorithm)
214-
payload, header = ::JWT.decode(token, 'secret', true, algorithm: CustomHS512Algorithm)
183+
payload = { data: 'test' }
184+
token = JWT.encode(payload, 'secret', CustomHS512Algorithm)
185+
# => "eyJhbGciOiJIUzUxMiJ9.eyJkYXRhIjoidGVzdCJ9.aBNoejLEM2WMF3TxzRDKlehYdG2ATvFpGNauTI4GSD2VJseS_sC8covrVMlgslf0aJM4SKb3EIeORJBFPtZ33w"
186+
187+
decoded_token = JWT.decode(token, 'secret', true, algorithm: CustomHS512Algorithm)
188+
# => [
189+
# {"data"=>"test"}, # payload
190+
# {"alg"=>"HS512"} # header
191+
# ]
215192
```
216193

217194
### Add custom header fields
@@ -220,30 +197,16 @@ The ruby-jwt gem supports custom [header fields](https://tools.ietf.org/html/rfc
220197
To add custom header fields you need to pass `header_fields` parameter
221198

222199
```ruby
223-
token = JWT.encode(payload, key, 'HS256', {})
224-
```
225-
226-
**Example:**
227-
228-
```ruby
229-
230200
payload = { data: 'test' }
231201

232-
# IMPORTANT: set nil as password parameter
233202
token = JWT.encode(payload, nil, 'none', { typ: 'JWT' })
203+
# => "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJkYXRhIjoidGVzdCJ9."
234204

235-
# eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJkYXRhIjoidGVzdCJ9.
236-
puts token
237-
238-
# Set password to nil and validation to false otherwise this won't work
239-
decoded_token = JWT.decode(token, nil, false)
240-
241-
# Array
242-
# [
243-
# {"data"=>"test"}, # payload
244-
# {"typ"=>"JWT", "alg"=>"none"} # header
245-
# ]
246-
puts decoded_token
205+
decoded_token = JWT.decode(token, nil, true, { algorithm: 'none' })
206+
# => [
207+
# {"data"=>"test"}, # payload
208+
# {"typ"=>"JWT", "alg"=>"none"} # header
209+
# ]
247210
```
248211

249212
## `JWT::Token` and `JWT::EncodedToken`
@@ -253,10 +216,14 @@ The `JWT::Token` and `JWT::EncodedToken` classes can be used to manage your JWTs
253216
### Signing and encoding a token
254217

255218
```ruby
256-
token = JWT::Token.new(payload: { exp: Time.now.to_i + 60, jti: '1234', sub: "my-subject" }, header: { kid: 'hmac' })
219+
payload = { exp: Time.now.to_i + 60, jti: '1234', sub: "my-subject" }
220+
header = { kid: 'hmac' }
221+
222+
token = JWT::Token.new(payload: payload, header: header)
257223
token.sign!(algorithm: 'HS256', key: "secret")
258224

259-
token.jwt # => "eyJhbGciOiJIUzI1N..."
225+
token.jwt
226+
# => "eyJraWQiOiJobWFjIiwiYWxnIjoiSFMyNTYifQ.eyJleHAiOjE3NTAwMDU0NzksImp0aSI6IjEyMzQiLCJzdWIiOiJteS1zdWJqZWN0In0.NRLcK6fYr3IdNfmncJePMWLQ34M4n14EgqSYrQIjL9w"
260227
```
261228

262229
### Verifying and decoding a token
@@ -284,7 +251,7 @@ encoded_token.payload # => { 'exp'=>1234, 'jti'=>'1234", 'sub'=>'my-subject' }
284251
encoded_token.header # {'kid'=>'hmac', 'alg'=>'HS256'}
285252
```
286253

287-
#### Keyfinders
254+
#### Using a keyfinder
288255

289256
A keyfinder can be used to verify a signature. A keyfinder is an object responding to the `#call` method. The method expects to receive one argument, which is the token to be verified.
290257

‎bin/console.rb‎

Lines changed: 1 addition & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,6 @@
33

44
require 'bundler/setup'
55
require 'jwt'
6-
7-
# You can add fixtures and/or initialization code here to make experimenting
8-
# with your gem easier. You can also use a different console, if you like.
9-
10-
# (If you use this, don't forget to add pry to your Gemfile!)
11-
# require "pry"
12-
# Pry.start
13-
146
require 'irb'
7+
158
IRB.start(__FILE__)

‎ruby-jwt.gemspec‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ Gem::Specification.new do |spec|
3535

3636
spec.add_development_dependency 'appraisal'
3737
spec.add_development_dependency 'bundler'
38+
spec.add_development_dependency 'irb'
3839
spec.add_development_dependency 'logger'
3940
spec.add_development_dependency 'rake'
4041
spec.add_development_dependency 'rspec'

0 commit comments

Comments
 (0)