Class: Net::IMAP::SASL::XOAuth2Authenticator
- Inherits:
-
Object
- Object
- Net::IMAP::SASL::XOAuth2Authenticator
- Defined in:
- lib/net/imap/sasl/xoauth2_authenticator.rb
Overview
Authenticator for the “XOAUTH2
” SASL mechanism. This mechanism was originally created for GMail and widely adopted by hosted email providers. XOAUTH2
has been documented by Google and Microsoft.
This mechanism requires an OAuth2 access token which has been authorized with the appropriate OAuth2 scopes to access the user’s services. Most of these scopes are not standardized—consult each service provider’s documentation for their scopes.
Although this mechanism was never standardized and has been obsoleted by “OAUTHBEARER
”, it is still very widely supported.
See Net::IMAP::SASL::OAuthBearerAuthenticator.
Instance Attribute Summary collapse
-
#oauth2_token ⇒ Object
(also: #secret)
readonly
An OAuth2 access token which has been authorized with the appropriate OAuth2 scopes to use the service for #username.
-
#username ⇒ Object
(also: #authzid)
readonly
It is unclear from Google’s original XOAUTH2 documentation, whether “User” refers to the authentication identity (
authcid
) or the authorization identity (authzid
).
Instance Method Summary collapse
-
#done? ⇒ Boolean
Returns true when the initial client response was sent.
-
#initial_response? ⇒ Boolean
:call-seq: initial_response? -> true.
-
#initialize(user = nil, token = nil, username: nil, oauth2_token: nil, authzid: nil, secret: nil) ⇒ XOAuth2Authenticator
constructor
:call-seq: new(username, oauth2_token, **) -> authenticator new(username:, oauth2_token:, **) -> authenticator new(authzid:, oauth2_token:, **) -> authenticator.
-
#process(_data) ⇒ Object
Returns the XOAUTH2 formatted response, which combines the
username
with theoauth2_token
.
Constructor Details
#initialize(user = nil, token = nil, username: nil, oauth2_token: nil, authzid: nil, secret: nil) ⇒ XOAuth2Authenticator
:call-seq:
new(username, oauth2_token, **) -> authenticator
new(username:, oauth2_token:, **) -> authenticator
new(authzid:, oauth2_token:, **) -> authenticator
Creates an Authenticator for the “XOAUTH2
” SASL mechanism, as specified by Google, Microsoft and Yahoo.
Properties
-
#username — the username for the account being accessed.
#authzid — an alias for #username.
Note that, unlike some other authenticators,
username
sets the authorization identity and not the authentication identity. The authenticated identity is established for the client with the OAuth token. -
#oauth2_token — An OAuth2.0 access token which is authorized to access the service for #username.
Any other keyword parameters are quietly ignored.
71 72 73 74 75 76 77 78 |
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 71 def initialize(user = nil, token = nil, username: nil, oauth2_token: nil, authzid: nil, secret: nil, **) @username = authzid || username || user or raise ArgumentError, "missing username (authzid)" @oauth2_token = oauth2_token || secret || token or raise ArgumentError, "missing oauth2_token" @done = false end |
Instance Attribute Details
#oauth2_token ⇒ Object (readonly) Also known as: secret
An OAuth2 access token which has been authorized with the appropriate OAuth2 scopes to use the service for #username.
44 45 46 |
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 44 def oauth2_token @oauth2_token end |
#username ⇒ Object (readonly) Also known as: authzid
It is unclear from Google’s original XOAUTH2 documentation, whether “User” refers to the authentication identity (authcid
) or the authorization identity (authzid
). The authentication identity is established for the client by the OAuth token, so it seems that username
must be the authorization identity.
Microsoft’s documentation for shared mailboxes clearly indicates that the Office 365 server interprets it as the authorization identity.
Although they should validate that the token has been authorized to access the service for username
, some servers appear to ignore this field, relying only the identity and scope authorized by the token.
35 36 37 |
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 35 def username @username end |
Instance Method Details
#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.
98 |
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 98 def done?; @done end |
#initial_response? ⇒ Boolean
:call-seq:
initial_response? -> true
XOAUTH2
can send an initial client response.
84 |
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 84 def initial_response?; true end |
#process(_data) ⇒ Object
Returns the XOAUTH2 formatted response, which combines the username
with the oauth2_token
.
88 89 90 91 92 |
# File 'lib/net/imap/sasl/xoauth2_authenticator.rb', line 88 def process(_data) build_oauth2_string(@username, @oauth2_token) ensure @done = true end |