class Net::IMAP::SASL::OAuthAuthenticator

Abstract base class for the SASL mechanisms defined in RFC7628:

OAUTHBEARER (OAuthBearerAuthenticator)
OAUTH10A

Attributes

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"

host [R]

Hostname to which the client connected. (optional)

last_server_response [R]

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

mthd [R]

HTTP method. (optional)

path [R]

HTTP path data. (optional)

port [R]

Service port to which the client connected. (optional)

post [R]

HTTP post data. (optional)

qs [R]

The query string. (optional)

query [R]

The query string. (optional)

username [R]

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

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

Public Class Methods

new (authzid: nil, host: nil, port: nil, username: nil, query: nil, mthd: nil, path: nil, post: nil, qs: nil, **)

Source

# 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

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.

Public Instance Methods

authorization

Source

# File lib/net/imap/sasl/oauthbearer_authenticator.rb, line 124
def authorization; raise "must be implemented by subclass" end

Value of the HTTP Authorization header

Implemented by subclasses.

done?

Source

# File lib/net/imap/sasl/oauthbearer_authenticator.rb, line 119
def done?; @done end

Returns true when the initial client response was sent.

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

initial_client_response

Source

# 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

The RFC7628 §3.1 formatted response.

process (data)

Source

# 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

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