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

Inherits:
Object
  • Object
show all
Includes:
GS2Header
Defined in:
lib/net/imap/sasl/oauthbearer_authenticator.rb

Overview

Abstract base class for the SASL mechanisms defined in RFC7628:

Direct Known Subclasses

OAuthBearerAuthenticator

Constant Summary

Constants included from GS2Header

GS2Header::NO_NULL_CHARS, GS2Header::RFC5801_SASLNAME

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from GS2Header

#gs2_authzid, #gs2_cb_flag, #gs2_header, gs2_saslname_encode

Constructor Details

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



84
85
86
87
88
89
90
91
92
93
94
95
 
# 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 ⇒ Object (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"



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

def authzid
  @authzid
end

#host ⇒ Object (readonly)

Hostname to which the client connected. (optional)



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

def host
  @host
end

#last_server_response ⇒ Object (readonly)

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



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

def last_server_response
  @last_server_response
end

#mthd ⇒ Object (readonly)

HTTP method. (optional)



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

def mthd
  @mthd
end

#path ⇒ Object (readonly)

HTTP path data. (optional)



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

def path
  @path
end

#port ⇒ Object (readonly)

Service port to which the client connected. (optional)



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

def port
  @port
end

#post ⇒ Object (readonly)

HTTP post data. (optional)



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

def post
  @post
end

#qs ⇒ Object (readonly) Also known as: query

The query string. (optional)



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

def qs
  @qs
end

Instance Method Details

#authorization ⇒ Object

Value of the HTTP Authorization header

Implemented by subclasses.



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

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

#done? ⇒ Boolean

Returns true when the initial client response was sent.

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

Returns:

  • (Boolean) 


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

def done?; @done end

#initial_client_response ⇒ Object

The RFC7628 §3.1 formatted response.



99
100
101
102
103
104
105
 
# 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) ⇒ Object

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



108
109
110
111
112
113
 
# 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