Skip to content

Commit cbbae6f

Browse files
author
Matthew Fisher
committed
docs(reference): SSL support for custom domains
1 parent 7367202 commit cbbae6f

6 files changed

Lines changed: 241 additions & 50 deletions

File tree

‎docs/managing_deis/configure-load-balancers.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ These ports need to be open on the load balancers:
1919
* 80 (for application traffic and for API calls to the controller)
2020
* 2222 (for traffic to the builder)
2121

22-
If you want to configure SSL termination on your load balancer, see :ref:`ssl-endpoints`.
22+
If you want to configure SSL termination on your load balancer, see :ref:`platform_ssl`.
2323

2424
A health check should be configured on the load balancer to send an HTTP request to /health-check at
2525
port 80 on all nodes in the Deis cluster. The health check endpoint returns an HTTP 200. This enables

‎docs/managing_deis/production_deployments.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,4 +55,4 @@ Enable TLS
5555
----------
5656

5757
Using TLS to encrypt traffic (including Deis client traffic, such as login credentials) is crucial.
58-
See :ref:`ssl-endpoints`.
58+
See :ref:`platform_ssl`.

‎docs/managing_deis/ssl-endpoints.rst‎

Lines changed: 16 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,73 +2,41 @@
22
:description: Configure SSL termination for your Deis cluster
33

44

5-
.. _ssl-endpoints:
5+
.. _platform_ssl:
66

7-
SSL/TLS Endpoints
8-
=================
7+
Installing SSL for the Platform
8+
===============================
99

1010
SSL/TLS is the standard security technology for establishing an encrypted link
1111
between a web server and a browser. This link ensures that all data passed between the web server
1212
and browsers remain private and integral.
1313

1414
To enable SSL for your cluster and all apps running upon it, you can add an SSL key to your load
15-
balancer. You must either provide an SSL certificate that was registered with a CA or provide your
16-
own self-signed SSL certificate.
15+
balancer. You must either provide an SSL certificate that was registered with a CA or provide
16+
:ref:`your own self-signed SSL certificate <creating_self_signed_ssl>`.
1717

1818

19-
Generating an SSL Certificate
20-
-----------------------------
19+
.. _load_balancer_ssl:
2120

22-
To generate your own self-signed SSL certificate for testing purposes, you can run the following:
23-
24-
.. code-block:: console
25-
26-
$ openssl genrsa -out server.key 2048
27-
$ openssl req -new -key server.key -out server.csr
28-
29-
This will create a private key and a Certificate Signing Request. This CSR is typically sent to a
30-
CA such as Verisign, but in this example we will be using it to sign our own SSL certificate.
31-
32-
Though most fields are self-explanatory, pay close attention to the following:
33-
34-
+--------------+-------------------------------------------------------------------------+
35-
| Field | Description |
36-
+==============+=========================================================================+
37-
| Country Name | The two letter code, in ISO 3166-1 format, of the country in which your |
38-
| | organization is based. |
39-
+--------------+-------------------------------------------------------------------------+
40-
| Common Name | This is the fully qualified domain name that you wish to secure. In |
41-
| | most cases, this will be a wildcard subdomain. |
42-
+--------------+-------------------------------------------------------------------------+
43-
44-
To generate a temporary certificate which is good for 365 days, issue the following command:
45-
46-
.. code-block:: console
47-
48-
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
49-
50-
.. note::
51-
52-
Some SSL vendors like RapidSSL will secure both the root domain and the www subdomain if you
53-
set the Common Name to www.example.com
54-
55-
See your vendor's documentation for more information.
56-
57-
58-
Installing the SSL Certificate
59-
------------------------------
21+
Installing SSL on a Load Balancer
22+
---------------------------------
6023

6124
On most cloud-based load balancers, you can install a SSL certificate onto the load balancer
6225
itself. This is the recommended way of enabling SSL onto a cluster, as any communication inbound to
6326
the cluster will be encrypted while the internal components of Deis will still communicate over
64-
HTTP. To enable SSL, you will need to open port 443 on the load balancer and forward it to port 80
65-
on the routers. For EC2, you'll also need to add port 443 in the security group settings for your
66-
load balancer.
27+
HTTP.
28+
29+
To enable SSL, you will need to open port 443 on the load balancer and forward it to port 80 on the
30+
routers. For EC2, you'll also need to add port 443 in the security group settings for your load
31+
balancer.
6732

6833
See your vendor's specific instructions on installing SSL on your load balancer. For EC2, see their
6934
documentation on `installing an SSL cert for load balancing`_. For Rackspace, see their
7035
`Product FAQ`_.
7136

37+
38+
.. _router_ssl:
39+
7240
Installing SSL on the Deis Routers
7341
----------------------------------
7442

‎docs/reference/domain-ssl.rst‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
:title: Using an SSL Certificate with Deis
2+
:description: Enabling and configuring SSL on applications using the SSL endpoint.
3+
4+
5+
.. _domain_ssl:
6+
7+
Using an SSL Certificate with Deis
8+
==================================
9+
10+
SSL is a cryptographic protocol that provides end-to-end encryption and integrity for all web
11+
requests. Apps that transmit sensitive data should enable SSL to ensure all information is
12+
transmitted securely.
13+
14+
To enable SSL on a custom domain, e.g., ``www.example.com``, use the SSL endpoint.
15+
16+
.. note::
17+
18+
``deis certs`` is only useful for custom domains. Default application domains are
19+
SSL-enabled already and can be accessed simply by using https,
20+
e.g. ``https://foo.deisapp.com`` (provided that you have :ref:`installed your wildcard
21+
certificate <router_ssl>` on the routers or :ref:`on the load balancer <load_balancer_ssl>`).
22+
23+
24+
Overview
25+
--------
26+
27+
Because of the unique nature of SSL validation, provisioning SSL for your domain is a multi-step
28+
process that involves several third-parties. You will need to:
29+
30+
1. Purchase an SSL certificate from your SSL provider
31+
2. Upload the cert to Deis
32+
33+
34+
Acquire SSL Certificate
35+
-----------------------
36+
37+
Purchasing an SSL cert varies in cost and process depending on the vendor. `RapidSSL`_ offers a
38+
simple way to purchase a certificate and is a recommended solution. If you’re able to use this
39+
provider, see `buy an SSL certificate with RapidSSL`_ for instructions.
40+
41+
42+
DNS and Domain Configuration
43+
----------------------------
44+
45+
Once the SSL certificate is provisioned and your cert is confirmed, you must route requests for
46+
your domain through Deis. Unless you've already done so, add the domain specified when generating
47+
the CSR to your app with:
48+
49+
.. code-block:: console
50+
51+
$ deis domains:add www.example.com -a foo
52+
Adding www.example.com to foo... done
53+
54+
55+
Attach the Certificate
56+
----------------------
57+
58+
Add your certificate, any intermediate certificates, and private key to the endpoint with the
59+
``certs:add`` command.
60+
61+
.. code-block:: console
62+
63+
$ deis certs:add server.crt server.key
64+
Adding SSL endpoint... done
65+
www.example.com
66+
67+
68+
Attach a Certificate Chain
69+
^^^^^^^^^^^^^^^^^^^^^^^^^^
70+
71+
Sometimes, your certificates (such as a self-signed or a cheap certificate) need additional
72+
certificates to establish the chain of trust. What you need to do is bundle all the certificates
73+
into one file and give that to Deis. Importantly, your site’s certificate must be the first one:
74+
75+
.. code-block:: console
76+
77+
$ cat server.crt server.ca > server.bundle
78+
79+
After that, you can add them to Deis with the ``certs:add`` command:
80+
81+
.. code-block:: console
82+
83+
$ deis certs:add server.bundle server.key
84+
Adding SSL endpoint... done
85+
www.example.com
86+
87+
88+
Endpoint Details
89+
----------------
90+
91+
You can verify the details of your domain's SSL configuration with ``deis certs``.
92+
93+
.. code-block:: console
94+
95+
$ deis certs
96+
Common Name Expires
97+
--------------- ----------------------
98+
www.example.com 2016-12-31T00:00:00UTC
99+
100+
101+
Testing SSL
102+
-----------
103+
104+
Use a command line utility like ``curl`` to test that everything is configured correctly for your
105+
secure domain.
106+
107+
.. note::
108+
109+
The -k option flag tells curl to ignore untrusted certificates.
110+
111+
Pay attention to the output. It should print ``SSL certificate verify ok``. If it prints something
112+
like ``common name: www.example.com (does not match 'www.somedomain.com')`` then something is not
113+
configured correctly.
114+
115+
Remove Certificate
116+
------------------
117+
118+
You can remove a certificate using the ``certs:remove`` command:
119+
120+
.. code-block:: console
121+
122+
$ deis certs:remove www.example.com
123+
Removing www.example.com... Done.
124+
125+
126+
Troubleshooting
127+
---------------
128+
129+
Here are some steps you can follow if your SSL endpoint is not working as you'd expect.
130+
131+
132+
Untrusted Certificate
133+
^^^^^^^^^^^^^^^^^^^^^
134+
135+
In some cases when accessing the SSL endpoint, it may list your certificate as untrusted.
136+
137+
If this occurs, it may be because it is not trusted by Mozilla’s list of `root CAs`_. If this is
138+
the case, your certificate may be considered untrusted for many browsers.
139+
140+
If you have uploaded a certificate that was signed by a root authority but you get the message that
141+
it is not trusted, then something is wrong with the certificate. For example, it may be missing
142+
`intermediary certificates`_. If so, download the intermediary certificates from your SSL provider,
143+
remove the certificate from Deis and re-run the ``certs:add`` command.
144+
145+
.. _`RapidSSL`: https://www.rapidssl.com/
146+
.. _`buy an SSL certificate with RapidSSL`: https://www.rapidssl.com/buy-ssl/
147+
.. _`root CAs`: https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/included/
148+
.. _`intermediary certificates`: http://en.wikipedia.org/wiki/Intermediate_certificate_authorities

‎docs/reference/index.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ Reference Guide
1111

1212
usage
1313
terms/index
14+
domain-ssl
15+
self-signed-certs
1416
client
1517
server/index
1618
api-v1.0

‎docs/reference/self-signed-certs.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
:title: Creating a Self-Signed SSL Certificate
2+
:description: How to generate a self-signed certificate for securing your application's endpoints
3+
4+
.. _creating_self_signed_ssl:
5+
6+
Creating a Self-Signed SSL Certificate
7+
======================================
8+
9+
When :ref:`using the domain ssl <domain_ssl>` feature for non-production applications or when
10+
:ref:`installing SSL for the platform <platform_ssl>`, you can avoid the costs associated with the SSL
11+
certificate by using a self-signed SSL certificate. Though the certificate implements full
12+
encryption, visitors to your site will see a browser warning indicating that the certificate should
13+
not be trusted.
14+
15+
16+
Prerequisites
17+
-------------
18+
19+
The openssl library is required to generate your own certificate. Run the following command in your
20+
local environment to see if you already have openssl installed.
21+
22+
.. code-block:: console
23+
24+
$ which openssl
25+
/usr/bin/openssl
26+
27+
If the which command does not return a path then you will need to install openssl yourself:
28+
29+
+----------------+---------------------------------+
30+
| If you have... | Install with... |
31+
+================+=================================+
32+
| Mac OS X | Homebrew: brew install openssl |
33+
+----------------+---------------------------------+
34+
| Windows | complete package .exe installed |
35+
+----------------+---------------------------------+
36+
| Ubuntu Linux | apt-get install openssl |
37+
+----------------+---------------------------------+
38+
39+
40+
Generate Private Key and Certificate Signing Request
41+
----------------------------------------------------
42+
43+
A private key and certificate signing request are required to create an SSL certificate. These can
44+
be generated with a few simple commands. When the openssl req command asks for a “challenge
45+
password”, just press return, leaving the password empty.
46+
47+
.. code-block:: console
48+
49+
$ openssl genrsa -des3 -passout pass:x -out server.pass.key 2048
50+
...
51+
$ openssl rsa -passin pass:x -in server.pass.key -out server.key
52+
writing RSA key
53+
$ rm server.pass.key
54+
$ openssl req -new -key server.key -out server.csr
55+
...
56+
Country Name (2 letter code) [AU]:US
57+
State or Province Name (full name) [Some-State]:California
58+
...
59+
A challenge password []:
60+
...
61+
62+
63+
Generate SSL Certificate
64+
------------------------
65+
66+
The self-signed SSL certificate is generated from the server.key private key and server.csr files.
67+
68+
.. code-block:: console
69+
70+
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
71+
72+
The server.crt file is your site certificate suitable for use with
73+
:ref:`Deis's SSL endpoint <domain_ssl>` along with the server.key private key.

0 commit comments

Comments
 (0)