Skip to content

Instantly share code, notes, and snippets.

@karanth
Last active July 19, 2023 22:12
Show Gist options
  • Save karanth/8420579 to your computer and use it in GitHub Desktop.
Save karanth/8420579 to your computer and use it in GitHub Desktop.
Notes on SASL and OAUTH2 for IMAP

SASL - Simple Authentication and Security Layer is NOT a security protocol. It is an interface or an abstraction providing pluggable authentication mechanisms to connection-oriented protocols. For example, the SASL interface in a system supporting the LDAP protocol may support Kerberos-based authentication though traditionally LDAP does not support Kerberos-based authentication or security. Another example is that SASL built into an IMAP server may allow Oauth2-based authentication or any new authentication mechanism to be plugged in, though traditionally an IMAP server may only be supporting password-based authentication.

From now on, mechanisms refer to authentication mechanisms like Kerberos-based authentication, OAuth2-based authentication or even plain text authentication and protocols refer to connection-oriented protocols like LDAP, IMAP, SMTP, etc.

The mechanisms are grouped and named. For example, Kerberos-based authentication falls under a mechanism name called GSSAPI.

How a protocol makes use of SASL is defined in something called a SASL Profile. The SASL Profile for a particular protocol defines how the protocol should advertise the mechanisms it supports, how the authentication is triggered and what are the messages that flow through the system.

C: A1 CAPABILITY
S: * CAPABILITY IMAP4rev1 UNSELECT IDLE NAMESPACE QUOTA ID XLIST CHILDREN X-GM-EXT-1 XYZZY SASL-IR AUTH=XOAUTH AUTH=XOAUTH2 AUTH=PLAIN AUTH=PLAIN-CLIENTTOKEN
S: A1 OK Thats all she wrote! sj10if20592874pac.132
C: A2 AUTHENTICATE XOAUTH2 dXNlcj1zb21ldXNlckBleGFtcGxlLmNvbQFhdXRoPUJlYXJlciB2RjlkZnQ0cW1UYzJOdmIzUmxja0JoZEhSaGRtbHpkR0V1WTI5dENnPT0BAQo=
S: A2 OK Success

Gmail's IMAP servers support Oauth2-based authentication mechanism using SASL. The protocol support for SASL is present in IMAP4. SASL profile details for these servers based on the example above are,

  • The authentication mechanisms supported by the IMAP server appears when the CAPABILITY command is executed. In the example below, it can be seen that SASL-IR is a capability supported with mechanisms like XOAUTH, XOAUTH2, PLAIN and PLAIN-CLIENTTOKEN. In other words, the SASL profile advertises supported mechanisms via this command. The SASL-IR is a variant of the SASL interface, that allows for an initial client response when the authentication is initiated, without having to wait for a server response. This saves a round-trip to the server.
  • The authentication is triggered by the client sending an AUTHENTICATE command followed by the name of the mechanism (XOAUTH2 in this case) as defined by rfc 3501.
  • The second parameter of the AUTHENTICATE command actually holds the token and other authentication information. The SASL profile dictates a Base64 encoded string for this parameter.
  • In the case of Gmail, the Base64 string construction is given below. The AUTHENTICATE command has to be terminated by a "\r\n".
  • The server returns OK or NO depending on authentication success/failure. The server may return NO even if the mechanism is not supported.
  • SASL-IR is at play as the initial client response is sent in the AUTHENTICATE.

SASL is not limited to OAuth2, an IMAP server can support any other mechanism too. Similarly, SASL is not limited to the IMAP protocol, it can support OAuth2 or any other protocol like, say SMTP.

base64("user=" + {User} + "^Aauth=Bearer " + {Access Token} + "^A^A")
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment