class Net::IMAP::SASL::XOAuth2Authenticator

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.

Attributes

authzid[R]

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.

oauth2_token[R]

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

secret[R]

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

username[R]

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.

Public Class Methods

new(username, oauth2_token, **) → authenticator click to toggle source
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.

# 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

Public Instance Methods

done? click to toggle source

Returns true when the initial client response was sent.

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

# File lib/net/imap/sasl/xoauth2_authenticator.rb, line 98
def done?; @done end
initial_response? → true click to toggle source

XOAUTH2 can send an initial client response.

# File lib/net/imap/sasl/xoauth2_authenticator.rb, line 84
def initial_response?; true end
process(_data) click to toggle source

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

# File lib/net/imap/sasl/xoauth2_authenticator.rb, line 88
def process(_data)
  build_oauth2_string(@username, @oauth2_token)
ensure
  @done = true
end