class Net::IMAP::SASL::OAuthAuthenticator - net-imap: Ruby Standard Library Documentation

# class Net::IMAP::SASL::OAuthAuthenticator

Abstract base class for the `SASL` mechanisms defined in RFC7628:

- OAUTHBEARER (`OAuthBearerAuthenticator`)

- OAUTH10A

### 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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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 net-imap-0.5.4/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