7 Authentication

Cuirass does not provide its own authentication mechanism; by default, any user can do anything via its web interface. To restrict this to only authorized users, one approach is to proxy the Cuirass web site via a web server such as Nginx and configure the web server to require client certificate verification for pages under the ‘/admin’ prefix. The following minimal Nginx configuration can be used to accomplish this on a Guix System:

(service nginx-service-type
         (nginx-configuration
          (server-blocks
           (list
            ;; TLS is required for authentication; serve the site via
            ;; HTTPS only.
            (nginx-server-configuration
             (listen '("80"))
             (raw-content
              (list "return 308 https://$host$request_uri;")))

            (nginx-server-configuration
             (listen '("443 ssl"))
             (server-name '("ci.your-host.org"))
             (ssl-certificate "/etc/certs/ci.your-host.org.crt")
             (ssl-certificate-key "/etc/certs/ci.your-host.org.key")
             (locations
              (list
               ;; Proxy the whole Cuirass web site...
               (nginx-location-configuration
                (uri "/")
                (body (list "proxy_pass http://localhost:8081;")))
               ;; ... but require authentication for the admin pages.
               (nginx-location-configuration
                (uri "~ ^/admin")
                (body
                 (list "if ($ssl_client_verify != SUCCESS) \
{ return 403; } proxy_pass http://localhost:8081;")))))
             (raw-content
              ;; Register your self-generated certificate authority.
              (list "ssl_client_certificate /etc/ssl-ca/certs/ca.crt;"
                    "ssl_verify_client optional;")))))))

Your host TLS certificate could have been obtained via Let’s Encrypt or directly via the openssl command, among other means. To create a private certificate authority (CA) that can sign user certificates, a convenience script is provided. It’s main requirement is to have the guix command available. It can be invoked like:

sudo -E ./etc/new-client-cert.scm --generate-ca

It should generate the /etc/ssl-ca/private/ca.key private key as well as the /etc/ssl-ca/certs/ca.crt certificate authority as used in the Nginx configuration above.

To issue a new user certificate, run the same script from your home directory with:

sudo -E ./etc/new-client-cert.scm

You will be asked to input the password for the CA private key, if any, and again for your new certificate; save it carefully. The script requires to run as root to have access to the private certificate authority key; it outputs the new user certificate files to the current working directory.

After your new CA-signed user certificate is generated, it needs to be registered with your web browser. To do so using GNU IceCat, for example, you can navigate to ‘Parameters -> Security -> Show certificates’ and then click the ‘Import...’ button and select your .pk12 personal certificate file. The web interface of Cuirass should now only allow authenticated users to perform administrative tasks.