class Net::IMAP::SASL::Authenticators

Registry for SASL authenticators

Registered authenticators must respond to #new or #call (e.g. a class or a proc), receiving any credentials and options and returning an authenticator instance. The returned object represents a single authentication exchange and must not be reused for multiple authentication attempts.

An authenticator instance object must respond to #process, receiving the server’s challenge and returning the client’s response. Optionally, it may also respond to #initial_response? and #done?. When #initial_response? returns true, #process may be called the first time with nil. When #done? returns false, the exchange is incomplete and an exception should be raised if the exchange terminates prematurely.

See the source for PlainAuthenticator, XOAuth2Authenticator, and ScramSHA1Authenticator for examples.

Public Class Methods

new(use_defaults: true, use_deprecated: true) click to toggle source

Create a new Authenticators registry.

This class is usually not instantiated directly. Use SASL.authenticators to reuse the default global registry.

When use_defaults is false, the registry will start empty. When use_deprecated is false, deprecated authenticators will not be included with the defaults.

# File lib/net/imap/sasl/authenticators.rb, line 36
def initialize(use_defaults: true, use_deprecated: true)
  @authenticators = {}
  return unless use_defaults
  add_authenticator "Anonymous"
  add_authenticator "External"
  add_authenticator "OAuthBearer"
  add_authenticator "Plain"
  add_authenticator "Scram-SHA-1"
  add_authenticator "Scram-SHA-256"
  add_authenticator "XOAuth2"
  return unless use_deprecated
  add_authenticator "Login"      # deprecated
  add_authenticator "Cram-MD5"   # deprecated
  add_authenticator "Digest-MD5" # deprecated
end

normalize_name(mechanism) click to toggle source

Normalize the mechanism name as an uppercase string, with underscores converted to dashes.

# File lib/net/imap/sasl/authenticators.rb, line 26
def self.normalize_name(mechanism) -(mechanism.to_s.upcase.tr(?_, ?-)) end

Public Instance Methods

add_authenticator(mechanism) click to toggle source

add_authenticator(mechanism, authenticator_class)

add_authenticator(mechanism, authenticator_proc)

Registers an authenticator for authenticator to use. mechanism is the name of the SASL mechanism implemented by authenticator_class (for instance, "PLAIN").

If mechanism refers to an existing authenticator, the old authenticator will be replaced.

When only a single argument is given, the authenticator class will be lazily loaded from Net::IMAP::SASL::#{name}Authenticator (case is preserved and non-alphanumeric characters are removed..

# File lib/net/imap/sasl/authenticators.rb, line 71
def add_authenticator(name, authenticator = nil)
  authenticator ||= begin
    class_name = "#{name.gsub(/[^a-zA-Z0-9]/, "")}Authenticator".to_sym
    auth_class = nil
    ->(*creds, **props, &block) {
      auth_class ||= Net::IMAP::SASL.const_get(class_name)
      auth_class.new(*creds, **props, &block)
    }
  end
  key = Authenticators.normalize_name(name)
  @authenticators[key] = authenticator
end

authenticator(mechanism, ...) → auth_session click to toggle source

Builds an authenticator instance using the authenticator registered to mechanism. The returned object represents a single authentication exchange and must not be reused for multiple authentication attempts.

All arguments (except mechanism) are forwarded to the registered authenticator’s #new or #call method. Each authenticator must document its own arguments.

Note: This method is intended for internal use by connection protocol code only. Protocol client users should see refer to their client’s documentation, e.g. Net::IMAP#authenticate.

# File lib/net/imap/sasl/authenticators.rb, line 111
def authenticator(mechanism, ...)
  key = Authenticators.normalize_name(mechanism)
  auth = @authenticators.fetch(key) do
    raise ArgumentError, 'unknown auth type - "%s"' % key
  end
  auth.respond_to?(:new) ? auth.new(...) : auth.call(...)
end

Also aliased as: new

mechanism?(name) click to toggle source

# File lib/net/imap/sasl/authenticators.rb, line 90
def mechanism?(name)
  key = Authenticators.normalize_name(name)
  @authenticators.key?(key)
end

names click to toggle source

Returns the names of all registered SASL mechanisms.

# File lib/net/imap/sasl/authenticators.rb, line 53
def names; @authenticators.keys end

new

Alias for: authenticator

remove_authenticator(name) click to toggle source

Removes the authenticator registered for name

# File lib/net/imap/sasl/authenticators.rb, line 85
def remove_authenticator(name)
  key = Authenticators.normalize_name(name)
  @authenticators.delete(key)
end