diff --git a/docs/content/concepts/authentication.md b/docs/content/concepts/authentication.md index 8f618696a..99952256b 100644 --- a/docs/content/concepts/authentication.md +++ b/docs/content/concepts/authentication.md @@ -62,6 +62,188 @@ The activation for the individual tenant: ![Enable Anonymous Download](../../images/security/anonymousDownload.png) +### Certificate Authentication by Reverse Proxy + +hawkBit offers a certificate-based authentication mechanism, referred to as Mutual TLS, which eliminates the need to share a security token with the server. To implement this, you'll require a reverse proxy deployed before the hawkBit server to handle authentication. This process involves obtaining certificates for both the client and the reverse proxy and configuring hawkBit accordingly. + +Initially, you'll need to obtain certificates for these components, which is not covered in this description. Once you have acquired certificates for both the client and the Hawkbit server, whether from the same or different Certificate Authorities (CAs), you'll need to place these certificates in their respective locations. + +- client_ca.crt signs client.crt +- server_ca.crt signs server.crt + +- Client has the client.crt, client.key and server_ca.crt +- Server has the server.crt, server.key and client_ca.crt + +Here is an example diagram that shows all the communication between the hawkBit, reverse proxy and client. + +![Example Reverse Proxy Architecture](../../images/security/exampleReverseProxyArchitecture.png) + +#### Example Nginx Reverse Proxy Configurations +After placing your certificates, you need to deploy your proxy server and apply the provided configurations. You can apply Mutual TLS specifically to the URL given below to implement the process only for devices using the Device Integration API: + +`hawkbit.dev.example.com/default/controller/` + +This ensures that other clients, like UI users, can connect to Hawkbit without requiring client certificates. They can use Username and Password in the Management API, eliminating the need for authentication and making it more user-friendly. + +```nginx +# Nginx Hawkbit Configurations + +# Gets the Common Name of the certificate from the client certificate. +map $ssl_client_s_dn $ssl_client_s_dn_cn { + default ""; + ~CN=(?[^,]+) $CN; +} + +server { + listen 80; + listen [::]:80; + + server_name hawkbit.dev.example.com www.hawkbit.dev.example.com; + server_tokens off; + + location /.well-known/acme-challenge/ { + root /var/www/certbot; + } + + location / { + return 301 https://hawkbit.dev.example.com$request_uri; + } +} + +server { + listen 443 ssl; + listen [::]:443 ssl; + + server_name hawkbit.dev.example.com; + + ssl_certificate /etc/nginx/ssl/live/hawkbit.dev.example.com/server.crt; + ssl_certificate_key /etc/nginx/ssl/live/hawkbit.dev.example.com/server.key; + + ssl_client_certificate /etc/nginx/client-cer/client_ca.crt; + ssl_verify_client optional; + ssl_verify_depth 3; + + + # For devices that is using device integration API, + # Mutual TLS is required. + location ~*/.*/controller/ { + if ($ssl_client_verify != SUCCESS) { + return 403; + } + + proxy_pass http://hawkbit.dev.example.com:8080; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + # Client certificate Common Name and Issuer Hash is required + # for auth in hawkbit. + proxy_set_header X-Ssl-Client-Cn $ssl_client_s_dn_cn; + proxy_set_header X-Ssl-Issuer-Hash-1 Hawkbit; + + # These are required for clients to upload and download software. + proxy_request_buffering off; + client_max_body_size 1000m; + } + + # For clients that is using UI or Management API + location / { + proxy_pass http://hawkbit.dev.example.com:8080; + proxy_set_header Host $http_host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_request_buffering off; + client_max_body_size 1000m; + } +} +``` +To authenticate the request to Hawkbit itself, the common name and issuer hash of the presented client certificate are required. The issuer hash of a certificate is the hash of the certificate that signed the client certificate, which in our case is the CA. + +You can use the following command to get the issuer hash: + +`openssl x509 -in client_certificate.crt -issuer_hash -noout` + +However, in the Nginx configuration, obtaining the issuer hash is not possible without addons. Therefore, this header is manually entered as Hawkbit. You can enter any value here as long as it is matched with the *Allow targets to authenticate via a certificate authenticated by a reverse proxy* setting in the hawkbit UI. + +When deploying Nginx, you will need a `.yml` file. Here's an example `docker-compose.yml` file for Nginx Docker. + +```yml +version: '3' + +services: + webserver: + image: nginx:latest + ports: + - 80:80 + - 443:443 + restart: always + volumes: + - ./nginx/conf/:/etc/nginx/conf.d/:ro + - ./certbot/www:/var/www/certbot/:ro + - ./certbot/conf/:/etc/nginx/ssl/:ro + - ./client-cer/:/etc/nginx/client-cer/ + - ./landing-page/:/etc/webserver/landing-page + certbot: + image: certbot/certbot:latest + volumes: + - ./certbot/www/:/var/www/certbot/:rw + - ./certbot/conf/:/etc/letsencrypt/:rw +``` +`/client-cer/:/etc/nginx/client-cer/` is the designated location for the certificate authority that has signed the client certificate. The presented client certificate will be verified against this CA. + +#### Swupdate Suricatta Configurations + +If the client is utilizing the SWUpdate Suricatta service, the configurations on the device or client side should also be adjusted as follows. Remember to change id, url and certificate names to your needs. + +The location of the config file is `/etc/swupdate/swupdate.conf` + +```yml +suricatta : +{ +tenant = "default"; +id = "device_id"; +url = "https://hawkbit.dev.example.com"; +nocheckcert = false; +cafile = "server_ca.crt"; +sslkey = "/etc/ssl/certs/client.key"; +sslcert = "/etc/ssl/certs/client.crt"; +}; +``` + +If your client service is a linux, you can use the command bellow to see the logs produced by the swupdate. + +`journalctl --follow -u swupdate` + +#### Hawkbit Configurations + +There are also some configurations that you need update when you deployed your hawkbit service. + +You need to add the given download settings to your hawkBit configurations so that hawkBit can generate the URLs according to the https that the client will use to download. If you're deploying hawkBit as a Docker container, add these configurations as environmental values in the docker-compose.yml file. Don't forget to replace "hostname" with your actual hostname. + +``` +hawkbit.artifact.url.protocols.download-http.rel=download-http +hawkbit.artifact.url.protocols.download-http.hostname=hawkbit.dev.example +hawkbit.artifact.url.protocols.download-http.protocol=https +hawkbit.artifact.url.protocols.download-http.supports=DMF,DDI +hawkbit.artifact.url.protocols.download-http.ref={protocol}://{hostnameRequest}/{tenant}/controller/v1/{controllerId}/softwaremodules/{softwareModuleId}/artifacts/{artifactFileName} +``` + +In Hawkbit's UI section, under system configuration, make sure to select Allow targets to authenticate via a certificate authenticated by a reverse proxy and input the issuer hash as "Hawkbit". This can be whetever you have configured in the nginx configuration in `proxy_set_header X-Ssl-Issuer-Hash-1` + +![Example Reverse Proxy Settings](../../images/security/exampleReverseProxySettings.png) + +After successfully generating your certificates with the correct chain, deploying your Nginx and Hawkbit services with appropriate configurations, and updating the settings on the device side, you will be able to establish a certificate-based authentication mechanism. This will eliminate the necessity of sharing a security token with the server. + +#### Testing + +You can test the communication by using the Curl command below to see if you successfully implemented Mutual TLS: + +`curl -L -v --cert client.crt --key client.key --cacert server_ca.crt https://hawkbit.dev.example.com/default/controller/v1/{device-id}` + +In the UI, after uploading an SWU package and requesting a firmware update, you can use the link below to attempt to install the software package. + +`curl -L -v --cert client.crt --key client.key --cacert server_ca.crt https://hawkbit.dev.example.com/default/controller/v1/{device-id}/softwaremodules/{artifact-id}/artifacts/hawkbit_updated_5.swu --output outputfile` + ## DMF API Authentication is provided by _RabbitMQ_ [vhost and user credentials](https://www.rabbitmq.com/access-control.html) that is used for the integration. diff --git a/docs/static/images/security/exampleReverseProxyArchitecture.png b/docs/static/images/security/exampleReverseProxyArchitecture.png new file mode 100644 index 000000000..dec5e6f30 Binary files /dev/null and b/docs/static/images/security/exampleReverseProxyArchitecture.png differ diff --git a/docs/static/images/security/exampleReverseProxySettings.png b/docs/static/images/security/exampleReverseProxySettings.png new file mode 100644 index 000000000..482630465 Binary files /dev/null and b/docs/static/images/security/exampleReverseProxySettings.png differ