1# Google Proxies for Enterprise Certificates (GA)
2
3## Certificate-based-access
4
5If you use [certificate-based access][cba] to protect your Google Cloud resources, the end user [device certificate][clientcert] is one of the credentials that is verified before access to a resource is granted. You can configure Google Cloud to use the device certificates in your operating system key store when verifying access to a resource from the gcloud CLI or Terraform by using the enterprise certificates feature.
6
7## Google Enterprise Certificate Proxies (ECP)
8
9Google Enterprise Certificate Proxies (ECP) are part of the [Google Cloud Zero Trust architecture][zerotrust] that enables mutual authentication with [client-side certificates][clientcert]. This repository contains a set of proxies/modules that can be used by clients or toolings to interact with certificates that are stored in [protected key storage systems][keystore].
10
11To interact the client certificates, application code should not need to use most of these proxies within this repository directly. Instead, the application should leverage the clients and toolings provided by Google such as [Cloud SDK](https://cloud.google.com/sdk) to have a more convenient developer experience.
12
13## Compatibility
14
15The following platforms/keystores are supported by ECP:
16
17- MacOS: __Keychain__
18- Linux: __PKCS#11__
19- Windows: __MY__
20
21## User Guide
22
23Before using ECP with your application/client, you should complete the policy configurations documented in [Enable CBA for Enterprise Certificate][enterprisecert]. The remainder of this README focuses on client configuration.
24
25### Quick Start
26
271. Install gcloud CLI (Cloud SDK) at: https://cloud.google.com/sdk/docs/install. Install with the bundled python option enabled.
28
29 1. **Note:** gcloud version 416.0 or newer is required. Version 430.0 or newer is recommended.
30
311. For macOS and Linux, run the install.sh script after downloading it to complete installation.
32 ```
33 $ ./google-cloud-sdk/install.sh
34 ```
351. Install the ECP helper component:
36 ```
37 $ gcloud components install enterprise-certificate-proxy
38 ```
391. Initialize ECP certificate configuration:
40
41 * **MacOS** `$ gcloud auth enterprise-certificate-config create macos --issuer=<CERT_ISSUER>`
42
43 * **Linux** `$ gcloud auth enterprise-certificate-config create linux --label=<CERT_LABEL> --module=<PKCS11_MODULE_PATH> --slot=<SLOT_ID>`
44
45 * **Windows** `$ gcloud auth enterprise-certificate-config create windows --issuer=<CERT_ISSUER> --provider=<PROVIDER> --store=<STORE>`
46
471. Enable usage of client certificates through gcloud CLI config command:
48 ```
49 $ gcloud config set context_aware/use_client_certificate true
50 ```
511. You can now use gcloud to access CBA-protected GCP resources. For example:
52 ```
53 $ gcloud pubsub topics list
54 ```
55
56### Manual Certificate Configuration
57
58ECP relies on a certificate configuration JSON file to read all the metadata information for locating the certificate.
59By default, it is named `certificate_config.json` and stored at the following location on the user's device:
60
61* **Linux and MacOS**: `~/.config/gcloud/certificate_config.json`
62* **Windows**: `%APPDATA%\gcloud\certificate_config.json`
63
64You can put the JSON file in the location of your choice and set the path to it using:
65
66```
67$ gcloud config set context_aware/certificate_config_file_path "<json file path>"
68```
69
70Another approach for setting the JSON file location is with the `GOOGLE_API_CERTIFICATE_CONFIG` environment variable.
71
72```
73$ export GOOGLE_API_CERTIFICATE_CONFIG="<json file path>"
74```
75
76Below are examples of the certificate configuration file:
77
78#### MacOS (Keychain)
79
80```json
81{
82 "cert_configs": {
83 "macos_keychain": {
84 "issuer": "YOUR_CERT_ISSUER"
85 }
86 },
87 "libs": {
88 "ecp": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/bin/ecp",
89 "ecp_client": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libecp.dylib",
90 "tls_offload": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libtls_offload.dylib"
91 },
92 "version": 1
93}
94```
95
96#### Windows (MyStore)
97
98```json
99{
100 "cert_configs": {
101 "windows_store": {
102 "store": "MY",
103 "provider": "current_user",
104 "issuer": "YOUR_CERT_ISSUER"
105 }
106 },
107 "libs": {
108 "ecp": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/bin/ecp.exe",
109 "ecp_client": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libecp.dll",
110 "tls_offload": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libtls_offload.dll"
111 },
112 "version": 1
113}
114```
115
116#### Linux (PKCS#11)
117
118```json
119{
120 "cert_configs": {
121 "pkcs11": {
122 "label": "YOUR_TOKEN_LABEL",
123 "user_pin": "YOUR_PIN",
124 "slot": "YOUR_SLOT",
125 "module": "The PKCS #11 module library file path"
126 }
127 },
128 "libs": {
129 "ecp": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/bin/ecp",
130 "ecp_client": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libecp.so",
131 "tls_offload": "[GCLOUD-INSTALL-LOCATION]/google-cloud-sdk/platform/enterprise_cert/libtls_offload.so"
132 },
133 "version": 1
134}
135```
136
137### Logging
138
139To enable logging set the `ENABLE_ENTERPRISE_CERTIFICATE_LOGS` environment variable.
140
141#### Example
142
143```
144$ export ENABLE_ENTERPRISE_CERTIFICATE_LOGS=1 # Now the enterprise-certificate-proxy will output logs to stdout.
145```
146
147## Building ECP binaries from source
148
149For amd64 MacOS, run `./build/scripts/darwin_amd64.sh`. The binaries will be placed in `build/bin/darwin_amd64` folder.
150
151For amd64 Linux, run `./build/scripts/linux_amd64.sh`. The binaries will be placed in `build/bin/linux_amd64` folder.
152
153For amd64 Windows, in powershell terminal, run `.\build\scripts\windows_amd64.ps1`. The binaries will be placed in `build\bin\windows_amd64` folder.
154Note that gcc is required for compiling the Windows shared library. The easiest way to get gcc on Windows is to download Mingw64, and add "gcc.exe" to the powershell path.
155
156## Contributing
157
158Contributions to this library are always welcome and highly encouraged. See the [CONTRIBUTING](./CONTRIBUTING.md) documentation for more information on how to get started.
159
160## License
161
162Apache - See [LICENSE](./LICENSE) for more information.
163
164[cba]: https://cloud.google.com/beyondcorp-enterprise/docs/securing-resources-with-certificate-based-access
165[clientcert]: https://en.wikipedia.org/wiki/Client_certificate
166[openssl]: https://wiki.openssl.org/index.php/Binaries
167[keystore]: https://en.wikipedia.org/wiki/Key_management
168[cloudsdk]: https://cloud.google.com/sdk
169[enterprisecert]: https://cloud.google.com/beyondcorp-enterprise/docs/enable-cba-enterprise-certificates
170[zerotrust]: https://cloud.google.com/blog/topics/developers-practitioners/zero-trust-and-beyondcorp-google-cloud
171
View as plain text