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

# class Net::IMAP::SASL::XOAuth2Authenticator

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`.

### Attributes

authzid[R]

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.

oauth2_token[R]

An OAuth2 access token which has been authorized with the appropriate OAuth2 scopes to use the service for `username`.

secret[R]

An OAuth2 access token which has been authorized with the appropriate OAuth2 scopes to use the service for `username`.

username[R]

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.

### Public Class Methods

new(username, oauth2_token, **) → authenticator click to toggle source
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.

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

### Public Instance Methods

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/xoauth2_authenticator.rb, line 98
    def done?; @done end

initial_response? → true click to toggle source

`XOAUTH2` can send an initial client response.

    # File net-imap-0.5.4/lib/net/imap/sasl/xoauth2_authenticator.rb, line 84
    def initial_response?; true end

process(_data) click to toggle source

Returns the XOAUTH2 formatted response, which combines the `username` with the `oauth2_token`.

    # File net-imap-0.5.4/lib/net/imap/sasl/xoauth2_authenticator.rb, line 88
    def process(_data)
      build_oauth2_string(@username, @oauth2_token)
    ensure
      @done = true
    end

### Private Instance Methods

build_oauth2_string(username, oauth2_token) click to toggle source

    # File net-imap-0.5.4/lib/net/imap/sasl/xoauth2_authenticator.rb, line 102
    def build_oauth2_string(username, oauth2_token)
      format("user=%s\1auth=Bearer %s\1\1", username, oauth2_token)
    end