Custom Xcode 9 Server Certificate

Question

Xcode Server that comes with Xcode 9 now automatically generates SSL certificates for communication between server and clients. It also uses this certificate when communicating with the Xcode Server REST API. Is there a way to specify or replace the autogenerated keys and use a certificate from a trusted third party (like LetsEncrypt)?

The apache configuration file located at

/Library/Developer/XcodeServer/Configuration/httpd_os_xcs.conf

contains this information:

Listen 443
<VirtualHost *:443>
    # Xcode Server uses its own self-signed certificates
    # only if no other SSL configurations for Apache have been found
    <IfModule !ssl_module>
        LoadModule ssl_module libexec/apache2/mod_ssl.so
        SSLEngine on
        SSLCertificateFile /Library/Developer/XcodeServer/Certificates/apache.crt
        SSLCertificateKeyFile /Library/Developer/XcodeServer/Certificates/apache.key
    </IfModule>
    [...]
    <IfModule mod_proxy.c>
        SSLProxyEngine On
        SSLProxyCheckPeerCN Off

        ProxyPass /xcode/internal/api https://127.0.0.1:20343/api retry=0 timeout=30
        ProxyPassReverse /xcode/internal/api https://127.0.0.1:20343/api
        ProxyPass /xcode/internal/socket.io https://127.0.0.1:20343/socket.io retry=0 timeout=30
        ProxyPassReverse /xcode/internal/socket.io https://127.0.0.1:20343/socket.io
    </IfModule>
    [...]
</VirtualHost>

I believe the certificate is also part of the apache.keychain file found at

/Library/Developer/XcodeServer/Keychains/apache.keychain

but I haven't been able to verify that.

Every time the Xcode Server service is started in Xcode, the apache.{crt/key} files as well as the httpd_os_xcs.conf files are overwritten, so simple replacing/modifying these files does not appear to be an option.

The only way forward I can see is to implement some other SSL configuration as suggested in the http_os_xcs.conf file, but I can't seem to get that to work either.

Any suggestions or solutions are greatly appreciated.

Answer 1

This is what worked for me on macOS Mojave (10.14).

Installing the certificate via the Server app

1. Install the "Server" app from the App Store (version 5.8)
2. Generate a server certificate request from the Server app for your domain
3. Send the request file to certificate provider to obtain a certificate
4. From the Server app import the certificate and set it in the dropdown "Secure services using"

These steps could be done in some other way, but initially I wanted to use a "blessed" macOS way, and then the problems started :)

I wanted to use this certificate directly by the system Apache (which is what serves the https://example.com/xcode page), but the documentation is lacking, the only thing I've found is this migration guide where they speak about mod_secure_transport, which should be used instead of mod_ssl. This guide assumes that it is already configured, but mod_secure_transport is not present in the default Mojave Apache configs (those reside in /etc/apache2).

So let's do it manually the old-school way:

Preparing the Apache certificate files manually

1. Copy your certificate file to /etc/apache2/server.crt
2. Find your certificate in Keychain app, and export your certificate private key in p12 format from there.

3. Convert your private key to the format expected by Apache:

   openssl pkcs12 -in exported_private_key.p12 -nodes -out server.key -nocerts
   

4. Copy server.key to /etc/apache2/server.key

Configuring Apache manually

In /etc/apache2/httpd.conf :

1. Uncomment these lines:

   LoadModule ssl_module libexec/apache2/mod_ssl.so
   ...
   LoadModule socache_shmcb_module libexec/apache2/mod_socache_shmcb.so
   

2. Find "IfModule ssl_module" section and add:

   SSLCertificateFile "/private/etc/apache2/server.crt"
   SSLCertificateKeyFile "/private/etc/apache2/server.key"
   

3. Test the config:

   sudo apachectl configtest
   

4. Restart:

   sudo apachectl restart
   

If all is good, it is ready, and you can observe the result at https://example.com/xcode