class Net::IMAP::SASL::OAuthAuthenticator

Abstract base class for the SASL mechanisms defined in RFC7628:

Attributes

authzid[R]

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]

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"

Public Class Methods

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

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.

# 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

Public Instance Methods

authorization click to toggle source

Value of the HTTP Authorization header

Implemented by subclasses.

# File lib/net/imap/sasl/oauthbearer_authenticator.rb, line 124
def authorization; raise "must be implemented by subclass" end
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/oauthbearer_authenticator.rb, line 119
def done?; @done end
initial_client_response click to toggle source

The RFC7628 §3.1 formatted response.

# 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) click to toggle source

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

# 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