Mail Access via XOAUTH2 or OAUTHBEARER deprecated
The OX middleware supports authentication against IMAP, SMTP and ManageSieve servers using
SASL=OAUTHBEARER mechanisms. This document describes how it can be used.
Primary mail account
- Obviously the mail server needs to support it. Dovecot does so by a specific passdb implementation.
- Your App Suite authentication plugin must provide OAuth Bearer tokens during sign-in and these must be stored within user sessions. Best out-of-the-box support is granted by using OpenID Connect 1.0 Single-Sign-On.
- For non-web clients accessing App Suite HTTP API, a secondary mechanism to obtain OAuth tokens for username/password login must be provided. Again, OpenID Connect 1.0 Single-Sign-On can provide that, if the IDM/AM system supports the "Resource Owner Password Credentials Flow". Alternatively, an authentication plugin based on plain OAuth 2.0 and that grant flow also exists.
- The mail server must accept the tokens that are issued to App Suite during sign-in. Therefore ensure scope, audience, etc.
- If you have a choice, make a decision whether to use XOAUTH2 (Google Proprietary) or OAUTHBEARER (RFC 7628). They are basically technically equivalent, while
OAUTHBEARERrequires larger SASL responses but therefore being an internet standard.
IMAP and SMTP
com.openexchange.mail.authType = <either "xoauth2" or "oauthbearer"> com.openexchange.mail.transport.authType = <either "xoauth2" or "oauthbearer">
Like for (master) password authentication, it is important to have
com.openexchange.mail.loginSource set properly! OAuth 2.0 for email always requires a combination of username and token.
com.openexchange.mail.passwordSource does not play a role when
authType refers to an OAuth type.
com.openexchange.mail.filter.passwordSource = session com.openexchange.mail.filter.preferredSaslMech = <either "XOAUTH2" or "OAUTHBEARER">
Like for IMAP/SMTP, ensure that
com.openexchange.mail.filter.credentialSource refers to a source that picks the right username at runtime!
With the described configuration, Middleware will check IMAP/SMTP/ManageSieve pre-authentication capabilities to contain the according SASL mechanism. It will then obtain the access token from the current user session (parameter
__session.oauth.access) and create and send the according SASL response.
On every HTTP API request the session access token is checked for validity, based on an expiry date (also set as session parameter:
__session.oauth.access.expiry) and usually some leap time to eagerly refresh the token.
If the token is expired or to-be-expired in shorter than the eager refresh time, the token gets refreshed. Per default, using the OpenID Connect 1.0 integration or the OAuth 2.0 Authentication Service, it looks for a refresh token stored as session parameter
__session.oauth.refresh and performs a refresh grant flow against the configured token endpoint.
If no refresh token was issued/stored in the session or token refresh fails with a permanent error, e.g.
invalid_grant, the App Suite session is terminated and the user forced to sign-in again.
External mail accounts
Currently only GMail is supported using
XOAUTH2 for IMAP. As a prerequisite, Google OAuth must be setup according to this guide. The application needs to have scope
https://mail.google.com/ applied. Please note that this usually requires to go through an expensive security audit, as Google claims this to be a "restricted scope".