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 the user’s services. Most of these scopes are not standardized—consult each service provider’s documentation for their scopes.

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, authzid: nil, secret: nil) ⇒ XOAuth2Authenticator

:call-seq:

new(username,  oauth2_token,  **) -> authenticator
new(username:, oauth2_token:, **) -> authenticator
new(authzid:,  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.

    #authzid — an alias for #username.

    Note that, unlike some other authenticators, username sets the authorization identity and not the authentication identity. The authenticated identity is established for the client with the OAuth token.

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

Any other keyword parameters are quietly ignored.



71
72
73
74
75
76
77
78
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 71

def initialize(user = nil, token = nil, username: nil, oauth2_token: nil,
               authzid: nil, secret: nil, **)
  @username = authzid || username || user or
    raise ArgumentError, "missing username (authzid)"
  @oauth2_token = oauth2_token || secret || token or
    raise ArgumentError, "missing oauth2_token"
  @done = false
end

Instance Attribute Details

#oauth2_token ⇒ Object (readonly) Also known as: secret

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



44
45
46
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 44

def oauth2_token
  @oauth2_token
end

#username ⇒ Object (readonly) Also known as: authzid

It is unclear from Google’s original XOAUTH2 documentation, whether “User” refers to the authentication identity (authcid) or the authorization identity (authzid). The authentication identity is established for the client by the OAuth token, so it seems that username must be the authorization identity.

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

Although they should validate that the token has been authorized to access the service for username, some servers appear to ignore this field, relying only the identity and scope authorized by the token.



35
36
37
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 35

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) 


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

def done?; @done end

#initial_response? ⇒ Boolean

:call-seq:

initial_response? -> true

XOAUTH2 can send an initial client response.

Returns:

  • (Boolean) 


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

def initial_response?; true end

#process(_data) ⇒ Object

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



88
89
90
91
92
 
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 88

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