Class: Net::IMAP::SASL::Authenticators

Inherits:
Object
  • Object
show all
Defined in:
lib/net/imap/sasl/authenticators.rb

Overview

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.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(use_defaults: true, use_deprecated: true) ⇒ Authenticators

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.



36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
 
# 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

Class Method Details

.normalize_name(mechanism) ⇒ Object

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



26
 
# File 'lib/net/imap/sasl/authenticators.rb', line 26

def self.normalize_name(mechanism) -(mechanism.to_s.upcase.tr(?_, ?-)) end

Instance Method Details

#add_authenticator(name, authenticator = nil) ⇒ Object

:call-seq:

add_authenticator(mechanism)
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..



71
72
73
74
75
76
77
78
79
80
81
82
 
# 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) ⇒ Object Also known as: new

:call-seq:

authenticator(mechanism, ...) -> auth_session

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.



111
112
113
114
115
116
117
 
# 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

#mechanism?(name) ⇒ Boolean

Returns:

  • (Boolean) 


90
91
92
93
 
# File 'lib/net/imap/sasl/authenticators.rb', line 90

def mechanism?(name)
  key = Authenticators.normalize_name(name)
  @authenticators.key?(key)
end

#names ⇒ Object

Returns the names of all registered SASL mechanisms.



53
 
# File 'lib/net/imap/sasl/authenticators.rb', line 53

def names; @authenticators.keys end

#remove_authenticator(name) ⇒ Object

Removes the authenticator registered for name



85
86
87
88
 
# File 'lib/net/imap/sasl/authenticators.rb', line 85

def remove_authenticator(name)
  key = Authenticators.normalize_name(name)
  @authenticators.delete(key)
end