github.com/greenboxal/deis@v1.12.1/docs/using_deis/app-ssl.rst (about)

     1  :title: Using an SSL Certificate with Deis
     2  :description: Enabling and configuring SSL on applications using the SSL endpoint.
     3  
     4  
     5  .. _app_ssl:
     6  
     7  Application SSL Certificates
     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  .. note::
    68  
    69      It may take up to one minute for the certificate to be available on the routers.
    70  
    71  
    72  Attach a Certificate Chain
    73  ^^^^^^^^^^^^^^^^^^^^^^^^^^
    74  
    75  Sometimes, your certificates (such as a self-signed or a cheap certificate) need additional
    76  certificates to establish the chain of trust. What you need to do is bundle all the certificates
    77  into one file and give that to Deis. Importantly, your site’s certificate must be the first one:
    78  
    79  .. code-block:: console
    80  
    81      $ cat server.crt server.ca > server.bundle
    82  
    83  After that, you can add them to Deis with the ``certs:add`` command:
    84  
    85  .. code-block:: console
    86  
    87      $ deis certs:add server.bundle server.key
    88      Adding SSL endpoint... done
    89      www.example.com
    90  
    91  
    92  Endpoint Details
    93  ----------------
    94  
    95  You can verify the details of your domain's SSL configuration with ``deis certs``.
    96  
    97  .. code-block:: console
    98  
    99      $ deis certs
   100      Common Name      Expires
   101      ---------------  ----------------------
   102      www.example.com  2016-12-31T00:00:00UTC
   103  
   104  
   105  Testing SSL
   106  -----------
   107  
   108  Use a command line utility like ``curl`` to test that everything is configured correctly for your
   109  secure domain.
   110  
   111  .. note::
   112  
   113      The -k option flag tells curl to ignore untrusted certificates.
   114  
   115  Pay attention to the output. It should print ``SSL certificate verify ok``. If it prints something
   116  like ``common name: www.example.com (does not match 'www.somedomain.com')`` then something is not
   117  configured correctly.
   118  
   119  Remove Certificate
   120  ------------------
   121  
   122  You can remove a certificate using the ``certs:remove`` command:
   123  
   124  .. code-block:: console
   125  
   126      $ deis certs:remove www.example.com
   127      Removing www.example.com... Done.
   128  
   129  
   130  Troubleshooting
   131  ---------------
   132  
   133  Here are some steps you can follow if your SSL endpoint is not working as you'd expect.
   134  
   135  
   136  Untrusted Certificate
   137  ^^^^^^^^^^^^^^^^^^^^^
   138  
   139  In some cases when accessing the SSL endpoint, it may list your certificate as untrusted.
   140  
   141  If this occurs, it may be because it is not trusted by Mozilla’s list of `root CAs`_. If this is
   142  the case, your certificate may be considered untrusted for many browsers.
   143  
   144  If you have uploaded a certificate that was signed by a root authority but you get the message that
   145  it is not trusted, then something is wrong with the certificate. For example, it may be missing
   146  `intermediary certificates`_. If so, download the intermediary certificates from your SSL provider,
   147  remove the certificate from Deis and re-run the ``certs:add`` command.
   148  
   149  .. _`RapidSSL`: https://www.rapidssl.com/
   150  .. _`buy an SSL certificate with RapidSSL`: https://www.rapidssl.com/buy-ssl/
   151  .. _`root CAs`: https://www.mozilla.org/en-US/about/governance/policies/security-group/certs/included/
   152  .. _`intermediary certificates`: http://en.wikipedia.org/wiki/Intermediate_certificate_authorities