Class: Net::IMAP::SASL::XOAuth2Authenticator

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

Overview

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 and Microsoft.

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.

See Net::IMAP::SASL

OAuthBearerAuthenticator.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(user = nil, token = nil, username: nil, oauth2_token: nil) ⇒ XOAuth2Authenticator

:call-seq:

new(username,  oauth2_token,  **) -> authenticator
new(username:, oauth2_token:, **) -> authenticator

Creates an Authenticator for the “XOAUTH2” SASL mechanism, as specified by Google, Microsoft and Yahoo.

Properties

  • #username — the username for the account being accessed.

  • #oauth2_token — An OAuth2.0 access token which is authorized to access the service for #username.

See the documentation for each attribute for more details.



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 50

def initialize(user = nil, token = nil, username: nil, oauth2_token: nil, **)
  @username = username || user or
    raise ArgumentError, "missing username"
  @oauth2_token = oauth2_token || token or
    raise ArgumentError, "missing oauth2_token"
  [username, user].compact.count == 1 or
    raise ArgumentError, "conflicting values for username"
  [oauth2_token, token].compact.count == 1 or
    raise ArgumentError, "conflicting values for oauth2_token"
  @done = false
end

Instance Attribute Details

#oauth2_token ⇒ Object (readonly)

An OAuth2 access token which has been authorized with the appropriate OAuth2 scopes to use the service for #username.



32
33
34
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 32

def oauth2_token
  @oauth2_token
end

#username ⇒ Object (readonly)

It is unclear from Google’s original XOAUTH2 documentation, whether “User” refers to the authentication identity (authcid) or the authorization identity (authzid). It appears to behave as authzid.

Microsoft’s documentation for shared mailboxes clearly indicate that the Office 365 server interprets it as the authorization identity.



28
29
30
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 28

def username
  @username
end

Instance Method Details

#done? ⇒ Boolean

Returns true when the initial client response was sent.

The authentication should not succeed unless this returns true, but it does not indicate success.

Returns:

  • (Boolean) 


80
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 80

def done?; @done end

#initial_response? ⇒ Boolean

:call-seq:

initial_response? -> true

PLAIN can send an initial client response.

Returns:

  • (Boolean) 


66
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 66

def initial_response?; true end

#process(_data) ⇒ Object

Returns the XOAUTH2 formatted response, which combines the username with the oauth2_token.



70
71
72
73
74
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 70

def process(_data)
  build_oauth2_string(@username, @oauth2_token)
ensure
  @done = true
end