123456789_123456789_123456789_123456789_123456789_

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

Relationships & Source Files
Inherits: Object
Defined in: lib/net/imap/sasl/xoauth2_authenticator.rb

Overview

Authenticator for the “XOAUTH2” ::Net::IMAP::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 OAuthBearerAuthenticator.

Class Method Summary

Instance Attribute Summary

Instance Method Summary

Constructor Details

.new(username, oauth2_token, **) ⇒ authenticator .new(username:, oauth2_token:, **) ⇒ authenticator .new(authzid:, oauth2_token:, **) ⇒ authenticator

Creates an Authenticator for the “XOAUTH2” ::Net::IMAP::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.

[ GitHub ] 

  


# 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



  

    #authzid   (readonly)
  



  

    

Alias for #username.


  



  [ GitHub ]


  

  


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



alias authzid username


  








  

    #done?  ⇒ Boolean  (readonly)
  



  

    

Returns true when the initial client response was sent.



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


  





  


  [ GitHub ]


  

  


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



def done?; @done end


  








  

    #initial_response?  ⇒ Boolean  (readonly)  



  

    

XOAUTH2 can send an initial client response.


  



  [ GitHub ]


  

  


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



def initial_response?; true end


  








  

    #oauth2_token   (readonly)
    Also known as: #secret
  



  

    

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


  



  [ GitHub ]


  

  


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



attr_reader :oauth2_token


  








  

    #secret   (readonly)
  



  

    

Alias for #oauth2_token.


  



  [ GitHub ]


  

  


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



alias secret oauth2_token


  








  

    #username   (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.


  



  [ GitHub ]


  

  


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



attr_reader :username


  







Instance Method Details



  

    #build_oauth2_string(username, oauth2_token)   (private)
  

  [ GitHub ]


  

  


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



def build_oauth2_string(username, oauth2_token)
  format("user=%s\1auth=Bearer %s\1\1", username, oauth2_token)
end


  








  

    #process(_data)  
  



  

    

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


  



  [ GitHub ]


  

  


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



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