forked from pivotal-cf/docs-ops-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathsecurity_config.html.md.erb
143 lines (111 loc) · 9.1 KB
/
security_config.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
---
title: Providing a Certificate for Your SSL/TLS Termination Point
owner: RelEng
---
<strong><%= modified_date %></strong>
This topic describes how to configure SSL/TLS termination for HTTP traffic in [Pivotal Cloud Foundry](https://network.pivotal.io/products/pivotal-cf) (PCF) Elastic Runtime with an SSL certificate, as part of the process of configuring Elastic Runtime for deployment.
## <a id="ssl_term"></a> About SSL/TLS Termination in PCF Elastic Runtime
When you deploy PCF, you must configure the SSL/TLS termination for HTTP traffic in your Elastic Runtime configuration. You can terminate SSL/TLS at any one of the following entry points into PCF:
* Gorouter
* Load balancer and Gorouter
* Load balancer
* HAProxy
The following table summarizes SSL/TLS termination options in PCF and provides guidance on which option to choose for your deployment.
<table border="1" class="nice">
<tr>
<th>If the following applies to you:</th>
<th>Then terminate SSL/TLS at:</th>
<th>Related topic and configuration procedure:</th>
</tr>
<tr>
<td><ul>
<li>You want the most performant and recommended option, and </li>
<li>You can use a single SAN certificate for your deployment for your wildcard domains.</li>
</ul></td>
<td>
<b>Gorouter only</b>.<br/><br/>Select the <b>Forward SSL to Elastic Runtime Router</b> in your Elastic Runtime network configuration.
</td>
<td><a href="../adminguide/securing-traffic.html#gorouter_term">Terminating SSL/TLS at the Gorouter Only</a>
</td>
</tr>
<tr>
<td>
<ul><li>You cannot use a single SAN certificate for all system and application domains for your deployment, or</li>
<li>You require Extended Validation (EV) certificates.</li>
</ul>
</td>
<td><b>Load balancer only</b>.<br/><br/>Select the <b>Forward unencrypted traffic to Elastic Runtime Router</b>
</td>
<td><a href="../adminguide/securing-traffic.html#lb_term">Terminating SSL/TLS at the Load Balancer</a>
</td>
</tr>
<tr>
<td><ul>
<li>You want a higher level of security, and</li>
<li>You do not mind a slightly less performant deployment, and</li>
<li>You can use a single SAN certificate on the Gorouter, either for all system and application domains (but with a different key than for the same certificates hosted on your load balancer) or for a single domain (but with hostname verification disabled on the load balancer).</li> </td>
<td><b>Load balancer and Gorouter</b>.<br/><br/>Select the <b>Forward SSL to Elastic Runtime Router</b> in your Elastic Runtime network configuration.
</td>
<td><a href="../adminguide/securing-traffic.html#lb_and_gorouter_term">Terminating SSL/TLS at Gorouter and Load Balancer</a>
</td>
</tr>
<tr>
<td><ul>
<li>You can use a single SAN certificate for your deployment for your wildcard domains, and</li>
<li>You are deploying a test or development environment, or</li>
<li>You do not mind a slightly less performant deployment.</li>
</ul>
</td>
<td>
<b>HA Proxy</b>.<br/><br/>Select the <b>Forward SSL to HA Proxy</b>.
</td>
<td><a href="./ssl-term-haproxy.html#haproxy">Terminating SSL/TLS at HA Proxy</a>
</td>
</tr>
</tr></table>
##<a id="certs"></a> Certificate Requirements for PCF
The following list describes the certificate requirements for deploying PCF.
* You must obtain at least one SSL/TLS certificate for your environment.
* In a production environment, use a signed SSL/TLS certificate (trusted) from a known certificate authority (CA).
* In a development or testing environment, you can use a trusted CA certificate or a self-signed certificate. You can generate a self-signed certificate with `openssl` or a similar tool, or use the Elastic Runtime Ops Manager interface to [generate a certificate](#ert_certgen) for you.
<p class="note"><strong>Note</strong>: Certificates generated in Elastic Runtime are signed by the Ops Manager Certificate Authority. They are not technically self-signed, but they are sometimes referred to as "Self-Signed Certificates" in the Ops Manager UI and throughout this documentation.</p>
* Certificates used in PCF must be encoded in the PEM format.
* When you generate a certificate, save the private key used to generate your certificate in a safe place. You must upload its contents to the Elastic Runtime networking configuration.
* The certificate on the Gorouter must be associated with the correct hostname so that HTTPS can validate the request.
* If wildcard certificates are not supported for some or all of your domains, then configure termination requests at the [load balancer only](#lb_term). In this type of deployment, the load balancer passes unencrypted traffic to the Gorouter. As a result, you avoid having to reissue and reinstall certificates on the Gorouter for every app or UAA security zone.
* Extended Validation (EV) certificates support multiple hostnames, like SAN, but do not support wildcards. For this reason, if EV certificates are required, then terminate TLS/SSL at the [load balancer only](#lb_term) for the same reason stated above. You can avoid having to reissue and reinstall certificates on the Gorouter for every app or UAA security zone.
### <a id="aws_certs"></a> Certificate Requirements on AWS
If you are deploying PCF on AWS, then the certificate that you configure in Elastic Runtime must match the certificate that you upload to AWS as a prerequisite to PCF deployment. For more information, see the [Upload an SSL Certificate](../customizing/cloudform-template.html#upload-cert) section of the [Deploying the CloudFormation Template for PCF on AWS](../customizing/cloudform-template.html) topic.
### <a id="gcp_certs"></a> Certificate Requirements on GCP
If you are deploying PCF on GCP, then you must add your certificate to both the frontend configuration of your HTTP Load Balancer and to the Gorouter (Elastic Runtime Router). For more information, see [Create Instance Groups and the HTTP(S) Load Balancer](../customizing/gcp-prepare-env.html#create-http-and-instance-group).
GCP load balancers actually forward both encrypted (WebSockets) and unencrypted (HTTP and TLS-terminated HTTPS) traffic to the Gorouter. When configuring the point-of-entry for a GCP deployment, select <b>Forward SSL to Elastic Runtime Router</b> in your Elastic Runtime network configuration. This point-of-entry selection accommodates this special characteristic of GCP deployments.
##<a id="create_or_obtain_certs"></a> Creating a Wildcard Certificate for PCF Deployments
This section describes how to create or generate a certificate for your PCF Elastic Runtime environment. If you are deploying to a production environment, you should obtain a certificate from a trusted authority (CA).
For internal development or testing environments, you have two options for creating a required SSL certificates.
* You can create a self-signed certificate, or
* You can have [Elastic Runtime generate the certificate](#ert_certgen) for you.
To create a certificate, you can use a wide variety of tools including OpenSSL, Java's keytool, Adobe Reader, and Apple's Keychain to generate a Certificate Signing Request (CSR).
In either case for either self-signed or trusted single certificates, apply the following rules when creating the CSR:
* Specify your registered wildcard domain as the `Common Name`. For example, `*.yourdomain.com`.
* If you are using a split domain setup that separates the domains for `apps` and `system` components (recommended), then enter the following values in the `Subject Alternative Name` of the certificate:
* `*.apps.yourdomain.com`
* `*.system.yourdomain.com`
* `*.login.system.yourdomain.com`
* `*.uaa.system.yourdomain.com`
* If you are using a single domain setup, then use the following values as the `Subject Alternative Name` of the certificate:
* `*.login.system.yourdomain.com`
* `*.uaa.system.yourdomain.com`
<p class="note"><strong>Note</strong>: SSL certificates generated for wildcard DNS records only work for a single domain name component or component fragment. For example, a certificate generated for <code>*.EXAMPLE.com</code> does not work for <code>*.apps.EXAMPLE.com</code> and <code>*.system.EXAMPLE.com</code>. The certificate must have both <code>*.apps.EXAMPLE.com</code> and <code>*.system.EXAMPLE.com</code> attributed to it. </p>
### <a id="ert_certgen"></a> Generating a RSA Certificate in Elastic Runtime
1. Navigate to the Ops Manager Installation Dashboard.
1. Click the **Elastic Runtime** tile in the Installation Dashboard.
1. Click **Networking**.
1. Click **Generate RSA Certificate** to populate the **Router SSL Termination Certificate and Private Key** fields with RSA certificate and private key information.
1. If you are using a split domain setup that separates the domains for `apps` and `system` components (recommended), then enter the following domains for the certificate:
* `*.yourdomain.com`
* `*.apps.yourdomain.com`
* `*.system.yourdomain.com`
* `*.login.system.yourdomain.com`
* `*.uaa.system.yourdomain.com`
For example, `*.example.com`, `*.apps.example.com`, `*.system.example.com`, `*.login.system.example.com`, `*.uaa.system.example.com`
<%= image_tag("generate-cert.png") %>