Configuration: OAuth2 - roundcube/roundcubemail GitHub Wiki
(since version 1.5-beta)
Connecting Roundcube via OAuth2 is now possible and requires a few configuration options which are to be explained on this page.
Prerequisites
- Registered Client App (Roundcube) with your OAuth2 provider service
- XOAUTH support for both IMAP and SMTP servers Roundcube connects to
First of all, your Roundcube installation needs to be registered as a client application with your OAuth2 provider. This will give you the necessary credentials (client-id and secret) to fill in the Roundcube config. It's also necessary to register the redirect URL to Roundcube at the provider. Use https://<your-roundcube-url>/index.php/login/oauth
for this. The token endpoint must support the client_secret_post authentication method.
Roundcube Config
All available config options are listed in the "OAuth" section of the config/defaults.inc.php
file inside your Roundcube installation along with examples for Gmail and Outlook.com. Copy them to your config.inc.php
file and adapt them according to your setup. Please do not edit the defaults.inc.php
as this will be replaced on your next update.
There are the mandatory config options required to enable OAuth in Roundcube:
oauth_provider
: Enable OAuth2 by defining a provider. Use 'gmail', 'outlook' or 'generic'.oauth_provider_name
: Provider name to be displayed on the login buttonoauth_client_id
: OAuth client ID for your Roundcube installationoauth_client_secret
: OAuth client secretoauth_auth_uri
: URI for OAuth user authentication (redirect)oauth_token_uri
: Endpoint for OAuth authentication requests (server-to-server)oauth_identity_uri
: Endpoint to query user identity if not provided in auth responseoauth_scope
: OAuth scopes to request (space-separated string)
For Roundcube it's mandatory to receive the email address (or username) of the connected user. This is used to identify returning users and also to authenticate at the IMAP and SMTP servers. Most OAuth providers will return a so called ID Token along with the access token. That ID token contains information about the connected user. This can be enforced by requesting a specific scope, in most cases openid
. If no such ID token is returned in the first place, Roundcube will connect to the configured oauth_identity_uri
in order to query the connected user's identity. Use the oauth_identity_fields
option to tell Roundcube which field of the identity information holds can canonical username.
Some OAuth servers (like Outlook) needs a nonce
parameter for security. This parameter can be passed using the oauth_auth_parameters
config option. For instance: $config['oauth_auth_parameters'] = ['nonce' => mt_rand()];
Setting IMAP and SMTP hosts
With OAuth2 enabled, it's important to set fixed values for email server connections servers.
Enter hostnames with prefix ssl://
to use implicit TLS, or use prefix tls://
to use STARTTLS.
default_host
: IMAP hostnamesmtp_server
: SMTP hostname (or %h to inherit fromdefault_host
)
Disabling the Roundcube Login Form
By default, Roundcube will still show the classic login form with username/password fields with an additional button "Login via XXX". If OAuth shall be the only option to login at Roundcube, simply set oauth_login_redirect
= true. This will immediately redirect to the oauth_auth_uri
instead of displaying Roundcube's login screen.
Troubleshooting
Authenticator error "insecure protocol"
When running Roundcube in a docker container behind a reverse proxy, the authentication backend may return the error Redirect URL is using an insecure protocol. http is only allowed for hosts with suffix localhost
when returning from the authentication page. Some OAuth2 backends, e.g. Authelia, refuse to redirect to unsecure sites, and Roundcube is not aware of being run via https since the reverse proxy takes care of it.
Solve by setting $config['use_https'] = true;
in the config file