Class: Net::IMAP::SASL::Authenticators
- Inherits:
-
Object
- Object
- Net::IMAP::SASL::Authenticators
- 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.
Instance Method Summary collapse
-
#add_authenticator(name, authenticator = nil) ⇒ Object
:call-seq: add_authenticator(mechanism) add_authenticator(mechanism, authenticator_class) add_authenticator(mechanism, authenticator_proc).
-
#authenticator(mechanism) ⇒ Object
(also: #new)
:call-seq: authenticator(mechanism, …) -> auth_session.
-
#initialize(use_defaults: true, use_deprecated: true) ⇒ Authenticators
constructor
Create a new Authenticators registry.
- #mechanism?(name) ⇒ Boolean
-
#names ⇒ Object
Returns the names of all registered SASL mechanisms.
-
#remove_authenticator(name) ⇒ Object
Removes the authenticator registered for
name
.
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.
32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 |
# File 'lib/net/imap/sasl/authenticators.rb', line 32 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 |
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..
67 68 69 70 71 72 73 74 75 76 77 78 |
# File 'lib/net/imap/sasl/authenticators.rb', line 67 def add_authenticator(name, authenticator = nil) key = -name.to_s.upcase.tr(?_, ?-) 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 @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.
107 108 109 110 111 112 113 |
# File 'lib/net/imap/sasl/authenticators.rb', line 107 def authenticator(mechanism, ...) key = -mechanism.to_s.upcase.tr(?_, ?-) 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
86 87 88 89 |
# File 'lib/net/imap/sasl/authenticators.rb', line 86 def mechanism?(name) key = -name.to_s.upcase.tr(?_, ?-) @authenticators.key?(key) end |
#names ⇒ Object
Returns the names of all registered SASL mechanisms.
49 |
# File 'lib/net/imap/sasl/authenticators.rb', line 49 def names; @authenticators.keys end |
#remove_authenticator(name) ⇒ Object
Removes the authenticator registered for name
81 82 83 84 |
# File 'lib/net/imap/sasl/authenticators.rb', line 81 def remove_authenticator(name) key = -name.to_s.upcase.tr(?_, ?-) @authenticators.delete(key) end |