Roda::RodaPlugins::Auth::

RequestMethods module

Roda Plugin API – declare methods included in the class of the request

Attributes

authed_handler RW: If successfully authenticated, this will be the handler that succeeded
authed_identity RW: If successfully authenticated, this will be the cached identity

Public Class Methods

included( mod )

Inclusion callback – add Loggability to the Request.

    # File lib/roda/plugins/auth.rb
159 def self::included( mod )
160     super
161     unless mod.respond_to?( :log_to )
162         mod.extend( Loggability )
163         mod.log_to( :ravn_tactical )
164     end
165 end

Public Instance Methods

authenticate( **options )

Attempt to authenticate the request using the given authentication options. If authentication succeeds, sets its authed_identity and returns a truthy value. Returns nil if unable to authenticate.

    # File lib/roda/plugins/auth.rb
220 def authenticate( **options )
221     credentials = self.authorization or return false
222 
223     return catch( :auth_result ) do
224         if (self.authed_identity = self.try_auth_handlers( **options ))
225             self.run_callback( :on_auth, **options )
226         end
227 
228         self.authed_identity
229     end
230 end

authorization()

Alias for: credentials

authorize( **options )

Attempt to authorize the request using the given authentication options. If authorization succeeds, returns a truthy value.

    # File lib/roda/plugins/auth.rb
235 def authorize( **options )
236     handler = self.authed_handler or return false
237     identity = self.authed_identity or return false
238 
239     return catch( :authz_result ) do
240         if (result = handler.check_authorization( identity, self, **options ))
241             self.run_callback( :on_authz, identity, **options )
242         end
243 
244         result
245     end
246 end

credentials()

Return the request’s parsed Authorization header (if it has one) as a Hash with the keys:

`:auth_scheme`	The name of the auth scheme being used.
`:auth_token`	The contents of the credential if it was the `token68` type.
`:auth_params`	The raw comma-separated key-value pairs of the credential if it was the auth-params type.

If it doesn’t have a valid Authorization header, it returns nil.

    # File lib/roda/plugins/auth.rb
196 def credentials
197     return @credentials ||= begin
198         unless (raw_credentials = self.headers[:authorization])
199             self.log.info "No Authorization header."
200             return nil
201         end
202 
203         self.log.debug "Parsing Authorization header..."
204         unless (match = raw_credentials.match( AUTHORIZATION_CREDENTIALS ))
205             self.log.error "Invalid Authorization header (%p)" % [ raw_credentials ]
206             return nil
207         end
208 
209         credentials = match.named_captures.transform_keys( &:to_sym )
210         self.log.debug "authorization credentials are: %p" % [ credentials ]
211         credentials
212     end
213 end

Also aliased as: authorization

is_authenticated?()

Returns true if the request has been authenticated.

    # File lib/roda/plugins/auth.rb
177 def is_authenticated?
178     return self.authed_identity ? true : false
179 end

run_callback( which, *args, **options )

Run the callback specified by which from the given options with the specified args.

    # File lib/roda/plugins/auth.rb
283 def run_callback( which, *args, **options )
284     if (callback = options[which])
285         self.log.debug "Running %s callback: %p with args = %p" % [ which, callback, args ]
286         return callback.call( self, *args, **options )
287     else
288         self.log.debug "No %s callback." % [ which ]
289         return *args
290     end
291 end

try_auth_handlers( **options )

Try the :schemes in the given options as authentication handlers, returning the first one that is valid and returns an identity object. Throws :auth_failure if any valid handler returns false explicitly.

    # File lib/roda/plugins/auth.rb
252 def try_auth_handlers( **options )
253     self.log.debug "Trying auth handlers from current auth schemes: %p" % [ options[:schemes] ]
254     handlers = options[:schemes] or return nil
255 
256     valid_handlers = handlers.values.
257         select {|obj| obj.respond_to?(:valid?) && obj.valid?(credentials, self) }
258 
259     self.log.debug "Found %d valid handlers." % [ valid_handlers.size ]
260     valid_handlers.each do |handler|
261         identity = handler.check_authentication( credentials, self, **options )
262         self.log.debug "Checking authentication via %p returned: %p" % [ handler, identity ]
263 
264         case identity
265         when FalseClass
266             self.log.info "%p indicated auth should fail" % [ handler ]
267             return nil
268         when NilClass
269             # No-op
270         else
271             self.log.info "%p indicated auth succeded: %p" % [ handler, identity ]
272             self.authed_handler = handler
273             return identity
274         end
275     end
276 
277     return nil
278 end