Class: Aker::Configuration

Inherits:
Object
  • Object
show all
Defined in:
lib/aker/configuration.rb

Overview

The representation of a configuration for Aker in a particular application, including authorities, customization parameters, and authentication modes.

Defined Under Namespace

Classes: Slice

Class Method Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Configuration) initialize(options = {}, &config)

Creates a new configuration. If a block is given, it will be evaluated using the DSL and appended to the new instance.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):



67
68
69
70
71
72
 
# File 'lib/aker/configuration.rb', line 67

def initialize(options={}, &config)
  (options[:slices] || self.class.default_slices).each do |slice|
    self.enhance(&slice.contents)
  end
  self.enhance(&config) if config
end

Class Method Details

+ add_default_slice(slice = nil, &block)

This method returns an undefined value.

Appends a slice to the default set of slices. A slice may be specified either as a Slice instance or as a block provided directly to this method.

Examples:

from an instance

class SomeSlice < Aker::Configuration::Slice
  def initialize
    super do
      register_authority :static, Aker::Authorities::Static
    end
  end
end
Aker::Configuration.add_default_slice(SomeSlice.new)

from a block

Aker::Configuration.add_default_slice do
  register_authority :static, Aker::Authorities::Static
end

Parameters:

  • slice (Slice) (defaults to: nil) —

    the slice to add, if a block isn't provided.

Since:

  • 2.2.0



47
48
49
50
51
52
53
54
 
# File 'lib/aker/configuration.rb', line 47

def add_default_slice(slice=nil, &block)
  if slice
    default_slices << slice
  end
  if block
    default_slices << Slice.new(&block)
  end
end

+ (Array<Slice>) default_slices

The default set of slices. These will be applied to all newly created instances. Changes to this array will not be reflected in existing configuration instances.

Returns:

Since:

  • 2.2.0



20
21
22
 
# File 'lib/aker/configuration.rb', line 20

def default_slices
  @default_slices ||= []
end

Instance Method Details

- add_parameters_for(group, params)

This method returns an undefined value.

Merges the given parameters into the specified group's.

Parameters:

  • group (Symbol) —

    the target group

  • params (Hash) —

    the parameters to merge in



213
214
215
 
# File 'lib/aker/configuration.rb', line 213

def add_parameters_for(group, params)
  nested_merge!(parameters_for(group), params)
end

- alias_authority(name, authority)

This method returns an undefined value.

Register an alias for an authority object. The alias is a symbol (or something that can be turned into one). The authority object is any single element that can be passed to #authorities=.

Aker does and Aker extensions may define shorter aliases for the authorities that they provide. In general, it's not expected that applications, even if they provide their own authorities, will need to configure aliases.

Parameters:

  • name (#to_sym) —

    the alias itself

  • authority (Symbol, String, Class, Object) —

    the authority object to alias. See #authorities= for more details.



244
245
246
 
# File 'lib/aker/configuration.rb', line 244

def alias_authority(name, authority)
  authority_aliases[name.to_sym] = authority
end

- (Array<Symbol>) api_modes

The names of the configured non-interactive authentication modes. Default is an empty list.

Returns:

  • (Array<Symbol>) —

    the names of the configured non-interactive authentication modes. Default is an empty list.



102
103
104
 
# File 'lib/aker/configuration.rb', line 102

def api_modes
  @api_modes ||= []
end

- api_modes=(*new_modes) Also known as: api_mode=

This method returns an undefined value.

Replaces the non-interactive authentication modes.

Parameters:

  • new_modes (List<#to_sym>) —

    the names of the desired modes



110
111
112
113
 
# File 'lib/aker/configuration.rb', line 110

def api_modes=(*new_modes)
  new_modes = new_modes.first if new_modes.size == 1 && Array === new_modes.first
  @api_modes = new_modes.compact.collect(&:to_sym)
end

- (Array<Object>) authorities

Returns the actual authority objects created based on the last call to #authorities=. Note that "authority" is concept and a set of methods (all of them optional), not a base class; see Authorities::Composite for more details.

Returns:

  • (Array<Object>) —

    the actual authority objects specified by this configuration



157
158
159
160
 
# File 'lib/aker/configuration.rb', line 157

def authorities
  raise "No authorities configured" unless authorities?
  @authorities
end

- authorities=(new_authorities)

This method returns an undefined value.

Set the authorities for this configuration.

Parameters:

  • new_authorities (Array<Symbol, String, Class, Object>) —

    each authority specification may take one of four forms.

    • A Symbol or a String will be resolved as an alias per the #authority_aliases. The Authorities documentation lists the built-in aliases. Extensions may provide others.
    • A Class will be instantiated, passing the configuration (this object) as the sole constructor parameter.
    • Any other object will be used unchanged.


178
179
180
 
# File 'lib/aker/configuration.rb', line 178

def authorities=(new_authorities)
  @authorities = new_authorities.collect { |a| build_authority(a) }
end

- (Boolean) authorities?

True if there are any authorities configured

Returns:

  • (Boolean) —

    true if there are any authorities configured



184
185
186
 
# File 'lib/aker/configuration.rb', line 184

def authorities?
  @authorities && !@authorities.empty?
end

- (Hash) authority_aliases

The map of aliases to authority objects.

Returns:

  • (Hash) —

    the map of aliases to authority objects.

See Also:



251
252
253
 
# File 'lib/aker/configuration.rb', line 251

def authority_aliases
  @authority_aliases ||= {}
end

- central(filename)

This method returns an undefined value.

Loads parameters from the given aker central parameters file.

Parameters:

  • filename (String) —

    the filename

See Also:



224
225
226
227
228
 
# File 'lib/aker/configuration.rb', line 224

def central(filename)
  params = ::Aker::CentralParameters.new(filename)

  params.each { |k, v| add_parameters_for(k, v) }
end

- (Aker::Authorities::Composite) composite_authority

Exposes a single object which aggregates all the authorities in this configuration.

Returns:



193
194
195
 
# File 'lib/aker/configuration.rb', line 193

def composite_authority
  @composite_authority ||= Aker::Authorities::Composite.new(self)
end

- (Configuration) enhance(&additional_config)

Updates the configuration via the DSL.

Returns:



78
79
80
81
 
# File 'lib/aker/configuration.rb', line 78

def enhance(&additional_config)
  Configurator.new(self, &additional_config)
  self
end

- install_middleware(where, builder)

This method returns an undefined value.

Installs the middleware configured under the given key in the given `Rack::Builder}. This method is primarily for internal library use.

Parameters:

  • where (:before_authentication, :after_authentication) —

    the set of middleware installers to use.

  • builder (#use) —

    the Rack::Builder-like object into which the middleware will be installed.

See Also:



338
339
340
341
342
343
 
# File 'lib/aker/configuration.rb', line 338

def install_middleware(where, builder)
  verify_middleware_location(where)
  (middleware_installers[where] || []).each do |installer|
    installer.call(builder)
  end
end

- (Object) logger

Retrieves the logger which aker will use for internal messages.

The default instance logs to standard error.

Returns:

  • (Object) —

    an object which conforms to the protocol of ruby's built-in Logger class



359
360
361
 
# File 'lib/aker/configuration.rb', line 359

def logger
  @logger ||= Logger.new($stderr)
end

- (Object) logger=(logger)

Specifies the logger aker will use for internal messages.

Parameters:

  • logger (Object) —

    an object which conforms to the protocol of ruby's built-in Logger class



368
369
370
 
# File 'lib/aker/configuration.rb', line 368

def logger=(logger)
  @logger = logger
end

- (Hash) parameters_for(group)

Returns the parameters for a particular group. Never returns nil.

Parameters:

  • group (Symbol) —

    the group of parameters to return

Returns:

  • (Hash) —

    the parameters of the specified group.



202
203
204
205
 
# File 'lib/aker/configuration.rb', line 202

def parameters_for(group)
  @parameter_groups ||= { }
  @parameter_groups[group] ||= { }
end

- (Symbol) portal

The portal to which this application belongs

Returns:

  • (Symbol) —

    the portal to which this application belongs



118
119
120
121
 
# File 'lib/aker/configuration.rb', line 118

def portal
  raise "No portal configured" unless portal?
  @portal
end

- portal=(portal)

This method returns an undefined value.

Set the portal to which this application belongs.

Portal is an optional authorization concept. If you have an authority which is based on an authorization store that provides group information for multiple groups of applications, Aker calls each group of applications a portal.

When an application declares that it is a part of a portal, authentication will fail for any user which is not a member of that portal. If you don't have an authority that provides that information, don't set a portal.

Parameters:

  • the (#to_sym) —

    new portal's name

See Also:



139
140
141
 
# File 'lib/aker/configuration.rb', line 139

def portal=(portal)
  @portal = nil_or_sym(portal)
end

- (Boolean) portal?

True if there is a portal set, else false

Returns:

  • (Boolean) —

    true if there is a portal set, else false



145
146
147
 
# File 'lib/aker/configuration.rb', line 145

def portal?
  @portal
end

- register_middleware_installer(where) {|#use| ... }

This method returns an undefined value.

Register a middleware-building block that will be used to insert middleware either before or after the Aker authentication middleware. This method requires a block. When it is time to actually install the middleware, the block will be yielded an object which behaves like a Rack::Builder. The block should attach any middleware it wishes to install using use.

Unlike the middleware associated with modes, this middleware will be inserted in the stack in regardless of any other settings.

This method is primarily intended for Aker and Aker extensions. Applications have complete control over their middleware stacks and so may build them however is appropriate.

Examples:

config.register_middleware_installer(:before_authentication) do |builder|
  builder.use IpFilter, '10.0.8.9'
end

Parameters:

  • where (:before_authentication, :after_authentication) —

    the relative location in the stack at which this installer should be invoked.

Yields:

  • (#use) —

    a Rack::Builder. Note that the yield is deferred until #install_middleware is invoked.

See Also:



316
317
318
319
 
# File 'lib/aker/configuration.rb', line 316

def register_middleware_installer(where, &installer)
  verify_middleware_location(where)
  (middleware_installers[where] ||= []) << installer
end

- register_mode(mode_class)

This method returns an undefined value.

Register a mode class to be used in this configuration. A mode class is a Warden strategy with some additional Aker elements on top.

Aker and Aker extensions register the the modes that they provide (using slices), so an application only needs to invoke this method if it provides its own custom mode.

Parameters:

  • mode_class (Class)

See Also:

Since:

  • 2.2.0



270
271
272
273
 
# File 'lib/aker/configuration.rb', line 270

def register_mode(mode_class)
  fail "#{mode_class.inspect} is not usable as a Aker mode" unless mode_class.respond_to?(:key)
  registered_modes << mode_class
end

- (Array<Class>) registered_modes

The mode classes that have been registered for use in this configuration.

Returns:

  • (Array<Class>)

See Also:



281
282
283
 
# File 'lib/aker/configuration.rb', line 281

def registered_modes
  @registered_modes ||= []
end

- (Symbol) ui_mode

The name of the configured interactive authentication mode. Default is :form.

Returns:

  • (Symbol) —

    the name of the configured interactive authentication mode. Default is :form.



86
87
88
 
# File 'lib/aker/configuration.rb', line 86

def ui_mode
  @ui_mode ||= :form
end

- ui_mode=(ui_mode)

This method returns an undefined value.

Sets the interactive authentication mode.

Parameters:

  • ui_mode (#to_sym, nil) —

    the name of the new mode; if nil, reset to the default



95
96
97
 
# File 'lib/aker/configuration.rb', line 95

def ui_mode=(ui_mode)
  @ui_mode = nil_or_sym(ui_mode)
end