openstax_auth 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c94d632ecd0b4eb33521d4ea151a1e4ad441904d27b36da6da1c152fe8d5ef68
4
- data.tar.gz: 9c59c1264d2fc58800a6dfe8ea6d65d3ecf32467466be038a61719f1e5711243
3
+ metadata.gz: 550cfea25994574d4796d2e9e3c3f6ac80bfcae9f255e20cf36e0bef77dccc59
4
+ data.tar.gz: bc6f51f5b4058c98d7da3c30d09e8d6b26ee93ad7af62f3426749efbd90173f1
5
5
  SHA512:
6
- metadata.gz: ea52d1b0e469d251152aa0fac49df44d666a073f59d1b15eee9570d7fe9126da4e014578c5a07643fe52156e3a2f9365875e28a119ee7e3dbdc0aa947acc2567
7
- data.tar.gz: 594a4c58eb9ba9ddf08253929b18ad493925d19462e380e5d57168b364cf803a5f88f81866bb9c7219baf3c4b3b6bff48565429057e43548803eb56a92c94ed8
6
+ metadata.gz: 6cc67717f9905fcc233f3a1cab4b8cee64cf055f26f19530888213a3a8dcace1ee35374ac8f9aa043bbe843103ef2213e631c0ba25f90842d8581f84be1771c3
7
+ data.tar.gz: ffb1b8fdb2a81c3ac10fe646f721957d323bebc6c852ad07b77b3b87c9093df2fe5e96a75172af058c5f909447cbe3ce020f0c31cd8dc3c986acfb550f6f55af
data/README.md CHANGED
@@ -20,11 +20,26 @@ And then execute:
20
20
 
21
21
  ## Usage
22
22
 
23
- This gem contains strategies for extracting user information from cookies. As OpenStax authentication cookies evolve over time, new strategies will be added and old ones will no longer be used.
23
+ This gem contains strategies for extracting user information from cookies and tokens. As OpenStax authentication cookies evolve over time, new strategies will be added and old ones will no longer be used.
24
+
25
+ ### Getting the current user
26
+
27
+ The simplest option is the top-level helper:
28
+
29
+ ```ruby
30
+ OpenStax::Auth.user_uuid(request)
31
+ ```
32
+
33
+ It picks the credential like this:
34
+
35
+ 1. If launch tokens are configured (see below) and the request has a non-blank `X-Launch-Token` header, only the launch token is used. An invalid token returns `nil`; it does **not** fall back to the SSO cookie.
36
+ 2. Otherwise it returns `OpenStax::Auth::Strategy2.user_uuid(request)`, exactly as before.
37
+
38
+ Apps that don't configure launch tokens get the same behavior as calling Strategy 2 directly.
24
39
 
25
40
  ### Strategy 2
26
41
 
27
- The only strategy in this gem.
42
+ Reads the Accounts SSO token from the `Authorization: Bearer` header or the SSO cookie.
28
43
 
29
44
  Configure the `strategy_2` settings:
30
45
 
@@ -41,6 +56,45 @@ end
41
56
 
42
57
  And then `require 'openstax/auth/strategy_2'` in the code that needs it.
43
58
 
59
+ ### Launch tokens
60
+
61
+ A launch token is a signed JWT (JWS) created by `@openstax/ts-utils` (`createLaunchSigner`) and sent in the `X-Launch-Token` request header. Its JWT header carries `iss`, `kid` and `alg`; its `sub` claim is the user's UUID. The public keys are fetched from `/.well-known/jwks.json` on the `iss` origin.
62
+
63
+ Configure the trusted domain to turn the feature on:
64
+
65
+ ```ruby
66
+ OpenStax::Auth.configure do |config|
67
+ config.launch_token.trusted_domain = 'openstax.org' # required to enable launch tokens
68
+
69
+ # Optional, with defaults:
70
+ config.launch_token.jwks_cache_ttl = 3600 # seconds to reuse fetched keys
71
+ config.launch_token.jwks_miss_ttl = 30 # seconds before an unknown kid can trigger another JWKS fetch
72
+ config.launch_token.open_timeout = 2 # JWKS HTTP connect timeout (seconds)
73
+ config.launch_token.read_timeout = 3 # JWKS HTTP read timeout (seconds)
74
+ config.launch_token.clock_skew = 30 # seconds of leeway for exp and nbf
75
+ end
76
+ ```
77
+
78
+ Then:
79
+
80
+ ```ruby
81
+ OpenStax::Auth::LaunchToken.user_uuid(request) # => "uuid" or nil
82
+ OpenStax::Auth::LaunchToken.verify(token) # => claims Hash or nil
83
+ ```
84
+
85
+ A token is accepted only if:
86
+
87
+ - the header `iss` is an `https` URL whose host is `trusted_domain` or a subdomain of it (checked before any network call),
88
+ - the payload `iss` equals the header `iss`,
89
+ - `alg` is RS256/384/512, PS256/384/512 or ES256/384/512 and matches the JWK's key type (`none` and HS* are rejected),
90
+ - the signature verifies against the JWK with the header's `kid`,
91
+ - `exp` is present and not past, and `nbf` (if present) is not in the future, allowing `clock_skew`,
92
+ - `sub` is a non-empty string.
93
+
94
+ Any failure, including network errors fetching the JWKS, returns `nil` rather than raising.
95
+
96
+ Keys are cached in-process (thread-safe) by JWKS URI and `kid`. An unknown `kid` triggers a refetch, but each JWKS URI is fetched at most once per `jwks_miss_ttl`, so random `kid` values can't force a fetch on every request. Redirects from the JWKS URL are not followed.
97
+
44
98
  ## Development
45
99
 
46
100
  After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
@@ -1,7 +1,7 @@
1
1
  module OpenStax
2
2
  module Auth
3
3
  class Configuration
4
- attr_reader :strategy2
4
+ attr_reader :strategy2, :launch_token
5
5
 
6
6
  class ConfigFields
7
7
  def self.attr_accessor(*vars, required: false)
@@ -25,8 +25,43 @@ module OpenStax
25
25
  attr_accessor :signature_algorithm, required: true
26
26
  end
27
27
 
28
+ # Settings for verifying OpenStax launch tokens (signed JWTs sent in the
29
+ # `X-Launch-Token` request header). Unlike strategy2, nothing here raises
30
+ # when unset: if `trusted_domain` is blank the feature is off.
31
+ class LaunchToken
32
+ DEFAULTS = {
33
+ # Keys fetched from a JWKS are reused for this many seconds
34
+ jwks_cache_ttl: 3600,
35
+ # After fetching a JWKS URI, an unknown kid (or a failed fetch) won't
36
+ # trigger another fetch of that URI for this many seconds
37
+ jwks_miss_ttl: 30,
38
+ # HTTP timeouts (seconds) for fetching the JWKS
39
+ open_timeout: 2,
40
+ read_timeout: 3,
41
+ # Allowed clock skew (seconds) when checking exp and nbf
42
+ clock_skew: 30
43
+ }.freeze
44
+
45
+ # The domain trusted to host launch token keys, eg "openstax.org".
46
+ # The JWKS host must equal it or be a subdomain of it.
47
+ attr_accessor :trusted_domain
48
+ attr_writer(*DEFAULTS.keys)
49
+
50
+ DEFAULTS.each do |name, default|
51
+ define_method(name) do
52
+ value = instance_variable_get("@#{name}")
53
+ value.nil? ? default : value
54
+ end
55
+ end
56
+
57
+ def configured?
58
+ !trusted_domain.nil? && !trusted_domain.to_s.strip.empty?
59
+ end
60
+ end
61
+
28
62
  def initialize
29
63
  @strategy2 = Strategy2.new
64
+ @launch_token = LaunchToken.new
30
65
  end
31
66
  end
32
67
 
@@ -0,0 +1,326 @@
1
+ require 'json/jwt'
2
+ require 'base64'
3
+ require 'net/http'
4
+ require 'uri'
5
+ require 'zlib'
6
+ require 'openstax/auth/configuration'
7
+
8
+ module OpenStax
9
+ module Auth
10
+ # Verifies OpenStax launch tokens: JWS tokens signed by @openstax/ts-utils
11
+ # (`createLaunchSigner`) and sent in the `X-Launch-Token` request header.
12
+ #
13
+ # The JWT header carries `iss`, `kid` and `alg`. The signing keys are
14
+ # published at `/.well-known/jwks.json` on the `iss` origin, which must be
15
+ # on the configured trusted domain. `sub` is the user's UUID.
16
+ module LaunchToken
17
+ HEADER_NAME = 'X-Launch-Token'.freeze
18
+
19
+ ALLOWED_ALGORITHMS = %w[
20
+ RS256 RS384 RS512
21
+ PS256 PS384 PS512
22
+ ES256 ES384 ES512
23
+ ].freeze
24
+
25
+ EC_CURVES = { 'ES256' => 'P-256', 'ES384' => 'P-384', 'ES512' => 'P-521' }.freeze
26
+
27
+ COMPACT_JWS = /\A[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\z/
28
+
29
+ RESCUED_ERRORS = [
30
+ JSON::JWT::Exception,
31
+ JSON::ParserError,
32
+ ArgumentError, # bad base64, bad key params
33
+ TypeError,
34
+ OpenSSL::OpenSSLError,
35
+ URI::Error,
36
+ SocketError,
37
+ SystemCallError, # ECONNREFUSED and friends
38
+ IOError,
39
+ Timeout::Error, # includes Net::OpenTimeout and Net::ReadTimeout
40
+ Net::ProtocolError,
41
+ Net::HTTPBadResponse, # malformed status line; not a ProtocolError
42
+ Net::HTTPHeaderSyntaxError,
43
+ Zlib::Error # bad gzip/deflate body
44
+ ].freeze
45
+
46
+ extend self
47
+
48
+ # Returns the user UUID (`sub`) from a valid launch token in the request's
49
+ # `X-Launch-Token` header, or nil.
50
+ def user_uuid(request)
51
+ claims = verify(token_from(request))
52
+ claims && claims['sub']
53
+ end
54
+
55
+ # Returns the raw `X-Launch-Token` header value, or nil if absent/blank.
56
+ def token_from(request)
57
+ token = request.headers[HEADER_NAME]
58
+ token = token.to_s.strip
59
+ token.empty? ? nil : token
60
+ end
61
+
62
+ def configured?
63
+ configuration.configured?
64
+ end
65
+
66
+ # Verifies a launch token and returns its claims as a Hash, or nil if the
67
+ # token is missing, malformed, untrusted, expired or otherwise invalid.
68
+ def verify(token)
69
+ return nil unless configured?
70
+ return nil unless token.is_a?(String) && COMPACT_JWS.match?(token)
71
+
72
+ encoded_header, encoded_payload, = token.split('.')
73
+ header = JSON.parse(Base64.urlsafe_decode64(encoded_header))
74
+ return nil unless header.is_a?(Hash)
75
+
76
+ # json-jwt assumes an object payload (it calls with_indifferent_access
77
+ # before checking the signature), so reject anything else up front.
78
+ # This also avoids a JWKS fetch for junk input.
79
+ payload = JSON.parse(Base64.urlsafe_decode64(encoded_payload.to_s))
80
+ return nil unless payload.is_a?(Hash)
81
+
82
+ alg = header['alg']
83
+ kid = header['kid']
84
+ iss = header['iss']
85
+ return nil unless ALLOWED_ALGORITHMS.include?(alg)
86
+ return nil unless kid.is_a?(String) && !kid.empty?
87
+
88
+ # Trust is checked before any network call
89
+ jwks_uri = trusted_jwks_uri(iss)
90
+ return nil if jwks_uri.nil?
91
+
92
+ jwk = key_cache.fetch(jwks_uri, kid) { |uri| fetch_jwks(uri) }
93
+ return nil if jwk.nil? || !key_matches_alg?(jwk, alg)
94
+
95
+ public_key = public_key_for(jwk)
96
+ return nil if public_key.nil?
97
+
98
+ jwt = JSON::JWT.decode(token, public_key, [alg.to_sym])
99
+ claims = jwt.to_hash
100
+ valid_claims?(claims, iss) ? claims : nil
101
+ rescue *RESCUED_ERRORS
102
+ nil
103
+ end
104
+
105
+ # Returns the JWKS URI for an `iss` value, or nil unless `iss` is an
106
+ # https URL whose host is the trusted domain or one of its subdomains.
107
+ def trusted_jwks_uri(iss)
108
+ return nil unless iss.is_a?(String) && !iss.empty?
109
+
110
+ issuer = URI.parse(iss)
111
+ return nil unless issuer.is_a?(URI::HTTPS) && issuer.host
112
+
113
+ host = issuer.host.downcase
114
+ return nil unless trusted_host?(host)
115
+
116
+ # Like JS `new URL('/.well-known/jwks.json', iss)`, but built from the
117
+ # canonical origin (no userinfo, query or fragment, lowercase host,
118
+ # default port omitted). Every spelling of an issuer then maps to one
119
+ # cache key, so varying it can't bypass the miss throttle.
120
+ port = issuer.port == issuer.default_port ? '' : ":#{issuer.port}"
121
+ "https://#{host}#{port}/.well-known/jwks.json"
122
+ rescue URI::Error
123
+ nil
124
+ end
125
+
126
+ def trusted_host?(host)
127
+ domain = configuration.trusted_domain.to_s.strip.downcase.sub(/\A\./, '')
128
+ host = host.to_s.downcase
129
+ return false if domain.empty? || host.empty?
130
+
131
+ host == domain || host.end_with?(".#{domain}")
132
+ end
133
+
134
+ # Fetches a JWKS document and returns { kid => JSON::JWK }. Redirects are
135
+ # not followed. Stubbed in specs.
136
+ def fetch_jwks(jwks_uri)
137
+ uri = URI.parse(jwks_uri)
138
+ response = Net::HTTP.start(
139
+ uri.host, uri.port,
140
+ use_ssl: true,
141
+ open_timeout: configuration.open_timeout,
142
+ read_timeout: configuration.read_timeout
143
+ ) do |http|
144
+ http.request(Net::HTTP::Get.new(uri.request_uri, 'Accept' => 'application/json'))
145
+ end
146
+ return {} unless response.is_a?(Net::HTTPSuccess)
147
+
148
+ parse_jwks(response.body)
149
+ end
150
+
151
+ def parse_jwks(body)
152
+ parsed = JSON.parse(body.to_s)
153
+ return {} unless parsed.is_a?(Hash) && parsed['keys'].is_a?(Array)
154
+
155
+ parsed['keys'].each_with_object({}) do |params, keys|
156
+ next unless params.is_a?(Hash) && params['kid'].is_a?(String)
157
+
158
+ keys[params['kid']] = JSON::JWK.new(params)
159
+ end
160
+ end
161
+
162
+ def key_cache
163
+ @key_cache_lock ||= Mutex.new
164
+ @key_cache_lock.synchronize { @key_cache ||= KeyCache.new(configuration) }
165
+ end
166
+
167
+ # Clears cached keys (for specs, or after changing configuration).
168
+ def reset_cache!
169
+ @key_cache_lock ||= Mutex.new
170
+ @key_cache_lock.synchronize { @key_cache = nil }
171
+ end
172
+
173
+ # In-process, thread-safe cache of JWKS keys keyed by (jwks_uri, kid).
174
+ #
175
+ # - A hit within `jwks_cache_ttl` is served without a fetch.
176
+ # - On a miss, the JWKS URI is fetched (one fetch at a time per URI, so
177
+ # concurrent requests at startup share a single fetch) and every key in
178
+ # the set is cached.
179
+ # - After a fetch, unknown kids for that URI return nil without another
180
+ # fetch for `jwks_miss_ttl`. This also throttles a failing endpoint, so
181
+ # random kids can't force a fetch on every request.
182
+ class KeyCache
183
+ MAX_ENTRIES = 1000
184
+ # Fetches are serialized per URI through a fixed pool of mutexes
185
+ # (striped by URI), so the lock bookkeeping stays bounded however many
186
+ # distinct issuers requests name.
187
+ LOCK_STRIPES = 64
188
+
189
+ def initialize(config, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
190
+ @config = config
191
+ @clock = clock
192
+ @lock = Mutex.new
193
+ @keys = {} # [jwks_uri, kid] => [jwk, expires_at]
194
+ @fetched_at = {} # jwks_uri => time of last fetch attempt
195
+ @uri_locks = Array.new(LOCK_STRIPES) { Mutex.new }
196
+ end
197
+
198
+ # Yields the jwks_uri to a block returning { kid => jwk } when a fetch
199
+ # is needed. Returns the JWK or nil.
200
+ def fetch(jwks_uri, kid)
201
+ cached = lookup(jwks_uri, kid)
202
+ return cached unless cached.nil?
203
+
204
+ uri_lock(jwks_uri).synchronize do
205
+ # Another thread may have fetched while we waited
206
+ cached = lookup(jwks_uri, kid)
207
+ return cached unless cached.nil?
208
+ return nil if recently_fetched?(jwks_uri)
209
+
210
+ keys = begin
211
+ yield(jwks_uri) || {}
212
+ ensure
213
+ @lock.synchronize do
214
+ @fetched_at[jwks_uri] = now
215
+ prune if @fetched_at.size > MAX_ENTRIES
216
+ end
217
+ end
218
+ store(jwks_uri, keys)
219
+ lookup(jwks_uri, kid)
220
+ end
221
+ end
222
+
223
+ private
224
+
225
+ def lookup(jwks_uri, kid)
226
+ @lock.synchronize do
227
+ jwk, expires_at = @keys[[jwks_uri, kid]]
228
+ jwk if jwk && expires_at > now
229
+ end
230
+ end
231
+
232
+ def recently_fetched?(jwks_uri)
233
+ @lock.synchronize do
234
+ fetched_at = @fetched_at[jwks_uri]
235
+ !fetched_at.nil? && now - fetched_at < miss_ttl
236
+ end
237
+ end
238
+
239
+ # Never throttle longer than keys live. Otherwise an expired key couldn't
240
+ # be refetched, and valid tokens would fail until the throttle ran out.
241
+ def miss_ttl
242
+ [@config.jwks_miss_ttl, @config.jwks_cache_ttl].min
243
+ end
244
+
245
+ # A non-empty fetch replaces the URI's whole key set, so keys retired
246
+ # from the JWKS stop being trusted at the next refresh. An empty result
247
+ # (error status, bad body) leaves cached keys alone, so a transient
248
+ # endpoint failure can't evict good keys.
249
+ def store(jwks_uri, keys)
250
+ return if keys.empty?
251
+
252
+ @lock.synchronize do
253
+ expires_at = now + @config.jwks_cache_ttl
254
+ @keys.delete_if { |(uri, _), _| uri == jwks_uri }
255
+ keys.each { |kid, jwk| @keys[[jwks_uri, kid]] = [jwk, expires_at] }
256
+ prune if @keys.size > MAX_ENTRIES || @fetched_at.size > MAX_ENTRIES
257
+ end
258
+ end
259
+
260
+ def uri_lock(jwks_uri)
261
+ @uri_locks[jwks_uri.hash % LOCK_STRIPES]
262
+ end
263
+
264
+ # Called with @lock held
265
+ def prune
266
+ time = now
267
+ @keys.delete_if { |_, (_, expires_at)| expires_at <= time }
268
+ @fetched_at.delete_if { |_, fetched_at| time - fetched_at >= miss_ttl }
269
+ # Still over the cap: keep the newest entries
270
+ if @fetched_at.size > MAX_ENTRIES
271
+ @fetched_at = @fetched_at.sort_by { |_, fetched_at| -fetched_at }.first(MAX_ENTRIES).to_h
272
+ end
273
+ if @keys.size > MAX_ENTRIES
274
+ @keys = @keys.sort_by { |_, (_, expires_at)| -expires_at }.first(MAX_ENTRIES).to_h
275
+ end
276
+ end
277
+
278
+ def now
279
+ @clock.call
280
+ end
281
+ end
282
+
283
+ private
284
+
285
+ def configuration
286
+ OpenStax::Auth.configuration.launch_token
287
+ end
288
+
289
+ # Malformed JWK params can raise almost anything from json-jwt/OpenSSL
290
+ def public_key_for(jwk)
291
+ jwk.to_key
292
+ rescue StandardError
293
+ nil
294
+ end
295
+
296
+ def key_matches_alg?(jwk, alg)
297
+ return false if jwk['alg'] && jwk['alg'] != alg
298
+ return false if jwk['use'] && jwk['use'] != 'sig'
299
+
300
+ case alg[0, 2]
301
+ when 'RS', 'PS' then jwk['kty'] == 'RSA'
302
+ when 'ES' then jwk['kty'] == 'EC' && jwk['crv'] == EC_CURVES[alg]
303
+ else false
304
+ end
305
+ end
306
+
307
+ def valid_claims?(claims, header_iss)
308
+ return false unless claims['iss'] == header_iss
309
+
310
+ sub = claims['sub']
311
+ return false unless sub.is_a?(String) && !sub.strip.empty?
312
+
313
+ now = Time.now.to_i
314
+ skew = configuration.clock_skew.to_i
315
+
316
+ exp = claims['exp']
317
+ return false unless exp.is_a?(Numeric) && now < exp + skew
318
+
319
+ nbf = claims['nbf']
320
+ return false unless nbf.nil? || (nbf.is_a?(Numeric) && now + skew >= nbf)
321
+
322
+ true
323
+ end
324
+ end
325
+ end
326
+ end
@@ -1,5 +1,5 @@
1
1
  module OpenStax
2
2
  module Auth
3
- VERSION = "0.2.0"
3
+ VERSION = "0.3.0"
4
4
  end
5
5
  end
data/lib/openstax_auth.rb CHANGED
@@ -1,7 +1,24 @@
1
1
  require "openstax/auth/version"
2
2
  require "openstax/auth/configuration"
3
+ require "openstax/auth/strategy_2"
4
+ require "openstax/auth/launch_token"
3
5
 
4
6
  module OpenStax
5
7
  module Auth
8
+ class << self
9
+ # Returns the current user's UUID, or nil.
10
+ #
11
+ # If launch tokens are configured and the request has an `X-Launch-Token`
12
+ # header, only that token is used: an invalid token returns nil and does
13
+ # not fall back to the SSO cookie. Otherwise this is the same as
14
+ # `Strategy2.user_uuid(request)`.
15
+ def user_uuid(request)
16
+ if LaunchToken.configured? && LaunchToken.token_from(request)
17
+ LaunchToken.user_uuid(request)
18
+ else
19
+ Strategy2.user_uuid(request)
20
+ end
21
+ end
22
+ end
6
23
  end
7
24
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: openstax_auth
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - JP Slavinsky
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2022-08-02 00:00:00.000000000 Z
11
+ date: 2026-11-04 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: json-jwt
@@ -83,6 +83,7 @@ files:
83
83
  - bin/console
84
84
  - bin/setup
85
85
  - lib/openstax/auth/configuration.rb
86
+ - lib/openstax/auth/launch_token.rb
86
87
  - lib/openstax/auth/strategy_2.rb
87
88
  - lib/openstax/auth/version.rb
88
89
  - lib/openstax_auth.rb
@@ -109,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
109
110
  - !ruby/object:Gem::Version
110
111
  version: '0'
111
112
  requirements: []
112
- rubygems_version: 3.1.4
113
+ rubygems_version: 3.3.27
113
114
  signing_key:
114
115
  specification_version: 4
115
116
  summary: Provides utilities to get user information from cookies within OpenStax Ruby