🔒 SASL XOAUTH2: document, kwargs

Author: nevans

lib/net/imap/sasl/xoauth2_authenticator.rb

@@ -1,22 +1,103 @@
 # frozen_string_literal: true
 
+# Authenticator for the "+XOAUTH2+" SASL mechanism.  This mechanism was
+# originally created for GMail and widely adopted by hosted email providers.
+# +XOAUTH2+ has been documented by
+# Google[https://developers.google.com/gmail/imap/xoauth2-protocol],
+# Microsoft[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth],
+# and Yahoo[https://senders.yahooinc.com/developer/documentation].
+#
+# This mechanism requires an OAuth2 +access_token+ which has been authorized
+# with the appropriate OAuth2 scopes to access IMAP.  These scopes are not
+# standardized---consult each email service provider's documentation.
+#
+# Although this mechanism was never standardized and has been obsoleted by
+# "+OAUTHBEARER+", it is still very widely supported.
 class Net::IMAP::SASL::XOAuth2Authenticator
 
+  ##
+  # :call-seq:
+  #   new(username,  oauth2_token,  **)       -> auth_ctx
+  #   new(authcid:,  oauth2_token:, **)       -> auth_ctx
+  #   new(**) {|propname, auth_ctx| propval } -> auth_ctx
+  #
+  # Creates an Authenticator for the "+XOAUTH2+" SASL mechanism, as specified by
+  # Google[https://developers.google.com/gmail/imap/xoauth2-protocol], and also
+  # documented by
+  # Microsoft[https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth],
+  # and Yahoo[https://senders.yahooinc.com/developer/documentation].  To use
+  # this, see Net::IMAP#authenticate or your client's authentication method.
+  #
+  # === Properties
+  #
+  # Both properties may be sent either as positional arguments or as keyword
+  # arguments.  If the same attribute is sent as both a positional arg and a
+  # keyword arg, an ArgumentError is raised.
+  #
+  # * #authcid, #username --- the identity whose #password is used.
+  #   Only <tt>:authcid</tt> will be sent to callbacks.
+  # * #oauth2_token --- An OAuth2.0 access token assigned to #username,
+  #   authorized to access IMAP.
+  #
+  # See the documentation for each attribute for more details.
+  #
+  def initialize(username_arg = nil, oauth2_token_arg = nil,
+                  username: nil, authcid: nil, oauth2_token: nil, **)
+    @authcid      = authcid  || username || username_arg
+    @oauth2_token = oauth2_token || oauth2_token_arg
+    @authcid      or raise ArgumentError, "missing authcid (username)"
+    @oauth2_token or raise ArgumentError, "missing oauth2_token"
+    [authcid, username, username_arg].compact.count == 1 or
+      raise ArgumentError, "conflicting values for authcid (username)"
+    [oauth2_token, oauth2_token_arg].compact.count == 1 or
+      raise ArgumentError, "conflicting values for oauth2_token"
+  end
+
+  # :call-seq:
+  #   initial_response? -> true
+  #
+  # +PLAIN+ can send an initial client response.
   def initial_response?; true end
 
-  def process(_data)
-    build_oauth2_string(@user, @oauth2_token)
-  end
+  ##
+  # method: authcid
+  # :call-seq: authcid -> string
+  #
+  # Authentication identity: the identity that matches the #oauth2_token.
+  #
+  # RFC-2831[https://tools.ietf.org/html/rfc2831] uses the term +username+.
+  # "Authentication identity" is the generic term used by
+  # RFC-4422[https://tools.ietf.org/html/rfc4422].
+  # RFC-4616[https://tools.ietf.org/html/rfc4616] and many later RFCs abbreviate
+  # to +authcid+.  #username is available as an alias for #authcid, but only
+  # <tt>:authcid</tt> will be sent to callbacks.
+  attr_reader :authcid
+  alias username authcid
 
-  private
+  ##
+  # method: oauth2_token
+  # :call-seq: oauth2_token -> string
+  #
+  # An OAuth2 access token for #authcid, which has been authorized with
+  # appropriate OAuth2 scopes to access IMAP.
+  attr_reader :oauth2_token
 
-  def initialize(user, oauth2_token)
-    @user = user
-    @oauth2_token = oauth2_token
+  # Returns the XOAUTH2 formatted response, which combines the +authcid+
+  # with the +oauth2_token+.
+  #
+  # [Note]
+  #   For simplicity, the same response is always generated, even when the
+  #   server sends error data in its challenge.  However, the \SASL
+  #   specification requires an empty response to acknowledge the error.  This
+  #   has little effect in practice, any response to the error results in an
+  #   tagged error response: generally +NO+, but potentially +BAD+.
+  def process(data)
+    @last_server_response = data
+    "user=%s\1auth=Bearer %s\1\1" % [username, oauth2_token]
   end
 
-  def build_oauth2_string(user, oauth2_token)
-    format("user=%s\1auth=Bearer %s\1\1", user, oauth2_token)
-  end
+  # Stores the most recent server "challenge".  When authentication fails, this
+  # may hold information about the failure reason, as JSON.
+  attr_reader :last_server_response
 
 end

test/net/imap/test_imap_authenticators.rb

@@ -176,13 +176,28 @@ def test_xoauth2_authenticator_matches_mechanism
     assert_kind_of(Net::IMAP::SASL::XOAuth2Authenticator, xoauth2("user", "tok"))
   end
 
-  def test_xoauth2
+  def test_xoauth2_response
     assert_equal(
       "user=username\1auth=Bearer token\1\1",
       xoauth2("username", "token").process(nil)
     )
   end
 
+  def test_xoauth2_kwargs
+    assert_equal(
+      "user=arg\1auth=Bearer kwarg\1\1",
+      xoauth2("arg", oauth2_token: "kwarg").process(nil)
+    )
+    assert_equal(
+      "user=authc\1auth=Bearer kwarg\1\1",
+      xoauth2(authcid: "authc", oauth2_token: "kwarg").process(nil)
+    )
+    assert_equal(
+      "user=user\1auth=Bearer kwarg\1\1",
+      xoauth2(username: "user", oauth2_token: "kwarg").process(nil)
+    )
+  end
+
   def test_xoauth2_supports_initial_response
     assert xoauth2("foo", "bar").initial_response?
     assert Net::IMAP::SASL.initial_response?(xoauth2("foo", "bar"))