123456789_123456789_123456789_123456789_123456789_

Class: Net::IMAP::SASL::OAuthAuthenticator

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
OAuthBearerAuthenticator
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, GS2Header
Inherits: Object
Defined in: lib/net/imap/sasl/oauthbearer_authenticator.rb

Overview

Abstract base class for the ::Net::IMAP::SASL mechanisms defined in RFC7628:

Constant Summary

GS2Header - Included

NO_NULL_CHARS, RFC5801_SASLNAME

Class Method Summary

Instance Attribute Summary

  • #authzid (also: #username) readonly

    Authorization identity: an identity to act as or on behalf of.

  • #done? ⇒ Boolean readonly

    Returns true when the initial client response was sent.

  • #host readonly

    Hostname to which the client connected.

  • #last_server_response readonly

    Stores the most recent server “challenge”.

  • #mthd readonly

    HTTP method.

  • #path readonly

    HTTP path data.

  • #port readonly

    Service port to which the client connected.

  • #post readonly

    HTTP post data.

  • #qs (also: #query) readonly

    The query string.

  • #query readonly

    Alias for #qs.

  • #username readonly

    Alias for #authzid.

Instance Method Summary

GS2Header - Included

#gs2_authzid

The RFC5801 §4 gs2-authzid header, when #authzid is not empty.
#gs2_cb_flag

The RFC5801 §4 gs2-cb-flag:
#gs2_header

The RFC5801 §4 gs2-header, which prefixes the #initial_client_response.
#gs2_saslname_encode

Encodes str to match RFC5801_SASLNAME.

Constructor Details

.new(authzid: nil, host: nil, port: nil, username: nil, query: nil, mthd: nil, path: nil, post: nil, qs: nil) ⇒ OAuthAuthenticator

Creates an RFC7628 OAuth authenticator.

Parameters

See child classes for required parameter(s). The following parameters are all optional, but it is worth noting that application protocols are allowed to require #authzid (or other parameters, such as #host or #port) as are specific server implementations.

  • optional #authzid ― Authorization identity to act as or on behalf of.

    optional #username — An alias for #authzid.

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

  • optional #host — Hostname to which the client connected.

  • optional #port — Service port to which the client connected.

  • optional #mthd — HTTP method

  • optional #path — HTTP path data

  • optional #post — HTTP post data

  • optional #qs — HTTP query string

    optional #query — An alias for #qs

Any other keyword parameters are quietly ignored.

[ GitHub ] 

  


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



def initialize(authzid: nil, host: nil, port: nil,
               username: nil, query: nil,
               mthd: nil, path: nil, post: nil, qs: nil, **)
  @authzid = authzid || username
  @host    = host
  @port    = port
  @mthd    = mthd
  @path    = path
  @post    = post
  @qs      = qs || query
  @done    = false
end


  







Instance Attribute Details



  

    #authzid   (readonly)
    Also known as: #username
  



  

    

Authorization identity: an identity to act as or on behalf of.  The identity form is application protocol specific.  If not provided or left blank, the server derives an authorization identity from the authentication identity.  The server is responsible for verifying the client’s credentials and verifying that the identity it associates with the client’s authentication identity is allowed to act as (or on behalf of) the authorization identity.



For example, an administrator or superuser might take on another role:



imap.authenticate "PLAIN", "root", passwd, authzid: "user"


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 29



attr_reader :authzid


  








  

    #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/oauthbearer_authenticator.rb', line 119



def done?; @done end


  








  

    #host   (readonly)
  



  

    

Hostname to which the client connected.  (optional)


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 33



attr_reader :host


  








  

    #last_server_response   (readonly)
  



  

    

Stores the most recent server “challenge”.  When authentication fails, this may hold information about the failure reason, as JSON.


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 53



attr_reader :last_server_response


  








  

    #mthd   (readonly)
  



  

    

HTTP method.  (optional)


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 39



attr_reader :mthd


  








  

    #path   (readonly)
  



  

    

HTTP path data.  (optional)


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 42



attr_reader :path


  








  

    #port   (readonly)
  



  

    

Service port to which the client connected.  (optional)


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 36



attr_reader :port


  








  

    #post   (readonly)
  



  

    

HTTP post data.  (optional)


  



  [ GitHub ]


  

  


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



attr_reader :post


  








  

    #qs   (readonly)
    Also known as: #query
  



  

    

The query string.  (optional)


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 48



attr_reader :qs


  








  

    #query   (readonly)
  



  

    

Alias for #qs.


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 49



alias query qs


  








  

    #username   (readonly)
  



  

    

Alias for #authzid.


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 30



alias username authzid


  







Instance Method Details



  

    #authorization  
  



  

    

Value of the HTTP Authorization header



Implemented by subclasses.


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 124



def authorization; raise "must be implemented by subclass" end


  








  

    #initial_client_response  
  



  

    

The RFC7628 §3.1 formatted response.


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 99



def initial_client_response
  kv_pairs = {
    host: host, port: port, mthd: mthd, path: path, post: post, qs: qs,
    auth: authorization, # authorization is implemented by subclasses
  }.compact
  [gs2_header, *kv_pairs.map {|kv| kv.join("=") }, "\1"].join("\1")
end


  








  

    #process(data)  
  



  

    

Returns initial_client_response the first time, then “^A”.


  



  [ GitHub ]


  

  


# File 'lib/net/imap/sasl/oauthbearer_authenticator.rb', line 108



def process(data)
  @last_server_response = data
  done? ? "\1" : initial_client_response
ensure
  @done = true
end