Merge pull request #6206 from jeffweilee/master

Refine Configure_https.md
2018-11-06 08:55:11 -05:00 · 2018-11-06 08:55:11 -05:00 · a5c0e09759
parent 56d57b0093 464fa3736c
commit a5c0e09759
1 changed files with 106 additions and 40 deletions
--- a/docs/configure_https.md
+++ b/docs/configure_https.md
@ -1,66 +1,129 @@
-# Configuring Harbor with HTTPS Access 
+# Configuring Harbor with HTTPS Access

 Because Harbor does not ship with any certificates, it uses HTTP by default to serve registry requests.  However, it is highly recommended that security be enabled for any production environment. Harbor has an Nginx instance as a reverse proxy for all services, you can use the prepare script to configure Nginx to enable https.

-## Getting a certificate
+In a test or development environment, you may choose to use a self-signed certificate instead of the one from a trusted third-party CA. The followings will show you how to create your own CA, and use your CA to sign a server certificate and a client certificate. 

-Assuming that your registry's **hostname** is **reg.yourdomain.com**, and that its DNS record points to the host where you are running Harbor. You first should get a certificate from a CA. The certificate usually contains a .crt file and a .key file, for example, **yourdomain.com.crt** and **yourdomain.com.key**.
-
-In a test or development environment, you may choose to use a self-signed certificate instead of the one from a CA. The below commands generate your own certificate:
-
-1) Create your own CA certificate:
+## Getting Certificate Authority

 ```
-  openssl req \
-    -newkey rsa:4096 -nodes -sha256 -keyout ca.key \
-    -x509 -days 365 -out ca.crt
+  openssl genrsa -out ca.key 4096
+```
+```
+  openssl req -x509 -new -nodes -sha512 -days 3650 \
+    -subj "/C=TW/ST=Taipei/L=Taipei/O=example/OU=Personal/CN=yourdomain.com" \
+    -key ca.key \
+    -out ca.crt
 ```
-2) Generate a Certificate Signing Request:

-If you use FQDN like **reg.yourdomain.com** to connect your registry host, then you must use **reg.yourdomain.com** as CN (Common Name). 
-Otherwise, if you use IP address to connect your registry host, CN can be anything like your name and so on:
+## Getting Server Certificate
+
+Assuming that your registry's **hostname** is **yourdomain.com**, and that its DNS record points to the host where you are running Harbor. In production environment, you first should get a certificate from a CA. In a test or development environment, you can use your own CA. The certificate usually contains a .crt file and a .key file, for example, **yourdomain.com.crt** and **yourdomain.com.key**.
+
+
+
+**1) Create your own Private Key:**

 ```
-  openssl req \
-    -newkey rsa:4096 -nodes -sha256 -keyout yourdomain.com.key \
-    -out yourdomain.com.csr
+  openssl genrsa -out yourdomain.com.key 4096
 ```
-3) Generate the certificate of your registry host:

-If you're using FQDN like **reg.yourdomain.com** to connect your registry host, then run this command to generate the certificate of your registry host:
+**2) Generate a Certificate Signing Request:**
+
+If you use FQDN like **yourdomain.com** to connect your registry host, then you must use **yourdomain.com** as CN (Common Name).

 ```
-  openssl x509 -req -days 365 -in yourdomain.com.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out yourdomain.com.crt
+  openssl req -sha512 -new \
+    -subj "/C=TW/ST=Taipei/L=Taipei/O=example/OU=Personal/CN=yourdomain.com" \
+    -key yourdomain.com.key \
+    -out yourdomain.com.csr 
 ```
-If you're using **IP**, say **192.168.1.101** to connect your registry host, you may instead run the command below:
+
+**3) Generate the certificate of your registry host:**
+
+Whether you're using FQDN like **yourdomain.com** or IP to connect your registry host, run this command to generate the certificate of your registry host which comply with Subject Alternative Name (SAN) and x509 v3 extension requirement:
+
+**v3.ext**

 ```
-  echo subjectAltName = IP:192.168.1.101 > extfile.cnf
+cat > v3.ext <<-EOF
+authorityKeyIdentifier=keyid,issuer
+basicConstraints=CA:FALSE
+keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
+extendedKeyUsage = serverAuth 
+subjectAltName = @alt_names

-  openssl x509 -req -days 365 -in yourdomain.com.csr -CA ca.crt -CAkey ca.key -CAcreateserial -extfile extfile.cnf -out yourdomain.com
-.crt
+[alt_names]
+DNS.1=yourdomain.com
+DNS.2=yourdomain
+DNS.3=hostname
+EOF
 ```
+
+```
+
+  openssl x509 -req -sha512 -days 3650 \
+    -extfile v3.ext \
+    -CA ca.crt -CAkey ca.key -CAcreateserial \
+    -in yourdomain.com.csr \
+    -out yourdomain.com.crt
+```
+
 ## Configuration and Installation
+
+**1) Configure Server Certificate and Key for Harbor**
+
 After obtaining the **yourdomain.com.crt** and **yourdomain.com.key** files, 
 you can put them into directory such as ```/root/cert/```:

 ```
-  cp yourdomain.com.crt /root/cert/
-  cp yourdomain.com.key /root/cert/ 
+  cp yourdomain.com.crt /data/cert/
+  cp yourdomain.com.key /data/cert/ 
 ```

+**2) Configure Server Certificate, Key and CA for Docker**

-Next, edit the file make/harbor.cfg , update the hostname and the protocol, and update the attributes ```ssl_cert``` and ```ssl_cert_key```:
+The Docker daemon interprets ```.crt``` files as CA certificates and ```.cert``` files as client certificates. 
+
+Convert server ```yourdomain.com.crt``` to ```yourdomain.com.cert```:
+
+```
+openssl x509 -inform PEM -in yourdomain.com.crt -out yourdomain.com.cert
+```
+Delpoy ```yourdomain.com.cert```, ```yourdomain.com.key```, and ```ca.crt``` for Docker:
+
+```
+  cp yourdomain.com.cert /etc/docker/certs.d/yourdomain.com/
+  cp yourdomain.com.key /etc/docker/certs.d/yourdomain.com/
+  cp ca.crt /etc/docker/certs.d/yourdomain.com/
+```
+
+The following illustrates a configuration with custom certificates:
+
+
+```
+/etc/docker/certs.d/
+    └── yourdomain.com:port   
+       ├── yourdomain.com.cert  <-- Server certificate signed by CA
+       ├── yourdomain.com.key   <-- Server key signed by CA
+       └── ca.crt               <-- Certificate authority that signed the registry certificate
+```
+
+Notice that you may need to trust the certificate at OS level. Please refer to the [Troubleshooting](#Troubleshooting) section below.
+
+**3) Configure Harbor**
+
+Edit the file ```harbor.cfg```, update the hostname and the protocol, and update the attributes ```ssl_cert``` and ```ssl_cert_key```:

 ```
  #set hostname
-  hostname = reg.yourdomain.com
+  hostname = yourdomain.com:port
  #set ui_url_protocol
  ui_url_protocol = https
  ......
  #The path of cert and key files for nginx, they are applied only the protocol is set to https 
-  ssl_cert = /root/cert/yourdomain.com.crt
-  ssl_cert_key = /root/cert/yourdomain.com.key
+  ssl_cert = /data/cert/yourdomain.com.crt
+  ssl_cert_key = /data/cert/yourdomain.com.key
 ```

 Generate configuration files for Harbor:
@ -72,7 +135,7 @@ Generate configuration files for Harbor:
 If Harbor is already running, stop and remove the existing instance. Your image data remain in the file system

 ```
-  docker-compose down  
+  docker-compose down -v
 ```
 Finally, restart Harbor:

@ -81,21 +144,26 @@ Finally, restart Harbor:
 ```
 After setting up HTTPS for Harbor, you can verify it by the following steps:

-1. Open a browser and enter the address: https://reg.yourdomain.com . It should display the user interface of Harbor.
+* Open a browser and enter the address: https://yourdomain.com. It should display the user interface of Harbor. 
+
+* Notice that some browser may still shows the warning regarding Certificate Authority (CA) unknown for security reason even though we signed certificates by self-signed CA and deploy the CA to the place mentioned above. It is because self-signed CA essentially is not a trusted third-party CA. You can import the CA to the browser on your own to solve the warning.
+
+* On a machine with Docker daemon, make sure the option "-insecure-registry" for https://yourdomain.com does not present. 
+
+* If you mapped nginx port 443 to another port, then you should instead create the directory ```/etc/docker/certs.d/yourdomain.com:port``` (or your registry host IP:port). Then run any docker command to verify the setup, e.g.

-2. On a machine with Docker daemon, make sure the option "-insecure-registry" does not present, and you must copy ca.crt generated in the above step to /etc/docker/certs.d/reg.yourdomain.com(or your registry host IP), if the directory does not exist, create it.
-If you mapped nginx port 443 to another port, then you should instead create the directory /etc/docker/certs.d/reg.yourdomain.com:port(or your registry host IP:port). Then run any docker command to verify the setup, e.g. 

 ```
-  docker login reg.yourdomain.com
+  docker login yourdomain.com
 ```
 If you've mapped nginx 443 port to another, you need to add the port to login, like below:

 ```
-  docker login reg.yourdomain.com:port
+  docker login yourdomain.com:port
 ```

-## Troubleshooting
+
+##Troubleshooting
 1. You may get an intermediate certificate from a certificate issuer. In this case, you should merge the intermediate certificate with your own certificate to create a certificate bundle. You can achieve this by the below command:  

    ```
@ -105,15 +173,13 @@ If you've mapped nginx 443 port to another, you need to add the port to login, l
   On Ubuntu, this can be done by below commands:  
   
    ```sh
-    cp youdomain.com.crt /usr/local/share/ca-certificates/reg.yourdomain.com.crt
+    cp yourdomain.com.crt /usr/local/share/ca-certificates/yourdomain.com.crt
    update-ca-certificates
    ```  
    
   On Red Hat (CentOS etc), the commands are:  
   
    ```sh
-    cp yourdomain.com.crt /etc/pki/ca-trust/source/anchors/reg.yourdomain.com.crt
+    cp yourdomain.com.crt /etc/pki/ca-trust/source/anchors/yourdomain.com.crt
    update-ca-trust
    ```
-    
-