Is autodiscover supported with cPanel's NGINX?

Question

Is autodiscover supported with cPanel's NGINX?

Answer

Autodiscover support has not yet been added to NGINX on cPanel. We have an internal case for this issue: ZC-4888

Workaround

Please keep in mind that if you choose to implement the following workaround, you must contact a systems administrator for assistance with the implementation and maintenance of the configuration.

Because official support for autodiscover with NGINX is not yet released you may find that this example configuration stops working at some point, or you may find that it needs additional customization to work on your specific server.

This example workaround configuration is provided as a courtesy example for your systems administrators to work from.

For each domain that needs autodiscover enabled, you must create a new configuration file in the /etc/nginx/conf.d directory. For example:
You must replace EXAMPLEDOMAIN.TLD with your own domain in all lowercase letters.

touch /etc/nginx/conf.d/autodiscover.EXAMPLEDOMAIN.TLD.conf

Then open the configuration file with your favorite editor and paste the two following server blocks into the file.
You must replace each instance of EXAMPLEDOMAIN.TLD with your own domain in lower case letters.

You must replace each instane of EXAMPLEUSERNAME with the cPanel username that owns the domain.

server {
listen 443 ssl;
listen [::]:443 ssl;

ssl_certificate /var/cpanel/ssl/apache_tls/EXAMPLEDOMAIN.TLD/combined;
ssl_certificate_key /var/cpanel/ssl/apache_tls/EXAMPLEDOMAIN.TLD/combined;

server_name autodiscover.EXAMPLEDOMAIN.TLD;

include conf.d/includes-optional/cloudflare.conf;

location /.well-known/cpanel-dcv {
root /home/EXAMPLEUSERNAME/public_html;
}

location /.well-known/pki-validation {
root /home/EXAMPLEUSERNAME/public_html;
}

location /.well-known/acme-challenge {
root /home/EXAMPLEUSERNAME/public_html;
}

location / {
# since proxy_set_header can not be done inside an if block we jump though hoops
# default value is empty because the header will be only sent if $value is not empty
set $upgrade_value "";
set $connection_value "";

if ($http_upgrade ~* ^websocket$) {
set $upgrade_value $http_upgrade;
set $connection_value "upgrade";
}

# In nginx you still need to use `http` for protocol in your url and not `ws`.
# The `ws` and `wss` protocol are required for browser, in the nginx side we add
# the headers below to handle the websockets over `http`.
proxy_set_header Upgrade $upgrade_value; # the header will be only sent if $upgrade_value is not empty
proxy_set_header Connection $connection_value; # the header will be only sent if $connection_value is not empty
include conf.d/includes-optional/cpanel-proxy.conf;
proxy_pass_header Upgrade; # this is hidden in cpanel-proxy.conf, but is needed for websockets
proxy_pass http://127.0.0.1:81/cgi-sys/autodiscover.cgi;
}
}

server {
listen 80;
listen [::]:80;

server_name autodiscover.EXAMPLEDOMAIN.TLD;

include conf.d/includes-optional/cloudflare.conf;

location /.well-known/cpanel-dcv {
root /home/EXAMPLEUSERNAME/public_html;
}

location /.well-known/pki-validation {
root /home/EXAMPLEUSERNAME/public_html;
}

location /.well-known/acme-challenge {
root /home/EXAMPLEUSERNAME/public_html;
}

location / {
# since proxy_set_header can not be done inside an if block we jump though hoops
# default value is empty because the header will be only sent if $value is not empty
set $upgrade_value "";
set $connection_value "";

if ($http_upgrade ~* ^websocket$) {
set $upgrade_value $http_upgrade;
set $connection_value "upgrade";
}

# In nginx you still need to use `http` for protocol in your url and not `ws`.
# The `ws` and `wss` protocol are required for browser, in the nginx side we add
# the headers below to handle the websockets over `http`.
proxy_set_header Upgrade $upgrade_value; # the header will be only sent if $upgrade_value is not empty
proxy_set_header Connection $connection_value; # the header will be only sent if $connection_value is not empty
include conf.d/includes-optional/cpanel-proxy.conf;
proxy_pass_header Upgrade; # this is hidden in cpanel-proxy.conf, but is needed for websockets
proxy_pass http://127.0.0.1:81/cgi-sys/autodiscover.cgi;
}
}

Once you have customized the server blocks to match your desired domain, you'll need to restart NGINX with the following command:

/scripts/restartsrv_nginx --restart

You can then test to see if autodiscover is working with the following curl command.

You must replace EXAMPLEDOMAIN.TLD with your own domain in all lowercase letters.

curl -kvsL -d '<EMailAddress>anyemailuser@EXAMPLEDOMAIN.TLD</EMailAddress>' http://autodiscover.EXAMPLEDOMAIN.TLD/autodiscover/autodiscover.xml

If it is working you'll see something similar to the following:

<Autodiscover xmlns="http://schemas.microsoft.com/exchange/autodiscover/responseschema/2006">
<Response xmlns="http://schemas.microsoft.com/exchange/autodiscover/outlook/responseschema/2006a">
<User>
<DisplayName>anyemailuser@EXAMPLEDOMAIN.TLD</DisplayName>
</User>
<Account>
<AccountType>email</AccountType>
<Action>settings</Action>
<Protocol>
<Type>IMAP</Type>
<Server>mail.EXAMPLEDOMAIN.TLD</Server>
<Port>993</Port>
<DomainRequired>off</DomainRequired>
<SPA>off</SPA>
<SSL>on</SSL>
<AuthRequired>on</AuthRequired>
<LoginName>anyemailuser@EXAMPLEDOMAIN.TLD</LoginName>
</Protocol>
<Protocol>
<Type>SMTP</Type>
<Server>mail.EXAMPLEDOMAIN.TLD</Server>
<Port>465</Port>
<DomainRequired>off</DomainRequired>
<SPA>off</SPA>
<SSL>on</SSL>
<AuthRequired>on</AuthRequired>
<LoginName>anyemailuser@EXAMPLEDOMAIN.TLD</LoginName>
</Protocol>
</Account>
</Response>
</Autodiscover>

Once that is working, you may then use AutoSSL to issue an SSL certificate for the autodiscover sub domain.