diff options
| author | Andy Zhao <andyzhao@google.com> | 2023-05-18 09:21:58 -0700 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2023-05-18 09:21:58 -0700 |
| commit | 399642e5e1719bdd006021a4778a87e1a329827a (patch) | |
| tree | d5b7a501ee54e936046c2340a128553441e8b721 | |
| parent | eed9f486bf88d2c79aa146f8cd2015dd334f480d (diff) | |
| download | googleapis-enterprise-certificate-proxy-399642e5e1719bdd006021a4778a87e1a329827a.tar.gz | |
doc: Update README.md to reflect GA usage instructions (#79)
| -rw-r--r-- | README.md | 61 |
1 files changed, 32 insertions, 29 deletions
@@ -1,4 +1,4 @@ -# Google Proxies for Enterprise Certificates (Preview) +# Google Proxies for Enterprise Certificates (GA) ## Certificate-based-access @@ -12,52 +12,56 @@ To interact the client certificates, application code should not need to use mos ## Compatibility -Currently ECP is in Preview stage and all the APIs and configurations are **subject to change**. - The following platforms/keystores are supported by ECP: - MacOS: __Keychain__ - Linux: __PKCS#11__ - Windows: __MY__ -## Prerequisites +## User Guide -Before using ECP with your application/client, you should follow the instructions [here][enterprisecert] to configure your enterprise certificate policies with Access Context Manager. +Before 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. ### Quick Start -1. Install gcloud CLI (Cloud SDK) at: https://cloud.google.com/sdk/docs/install. - - 1. **Note:** gcloud version 416.0 or newer is required. - -1. `$ gcloud components install enterprise-certificate-proxy`. - -1. **MacOS ONLY** +1. Install gcloud CLI (Cloud SDK) at: https://cloud.google.com/sdk/docs/install. Install with the bundled python option enabled. - 1. `$ gcloud config virtualenv create` + 1. **Note:** gcloud version 416.0 or newer is required. Version 430.0 or newer is recommended. - 1. `$ gcloud config virtualenv enable` - -1. Create a new JSON file at `~/.config/gcloud/certificate_config.json`: - - - Alternatively you can put the JSON in the location of your choice and set the path to it using: +1. For macOS and Linux, run the install.sh script after downloading it to complete installation. + ``` + $ ./google-cloud-sdk/install.sh + ``` +1. Install the ECP helper component: + ``` + $ gcloud components install enterprise-certificate-proxy + ``` +1. Initialize ECP certificate configuration: - `$ gcloud config set context_aware/enterprise_certificate_config_file_path "<json file path>"`. + * **MacOS** `$ gcloud auth enterprise-certificate-config create macos --issuer=<CERT_ISSUER>` - - Another approach for setting the JSON file location is setting the location with the `GOOGLE_API_CERTIFICATE_CONFIG` environment variable. + * **Linux** `$ gcloud auth enterprise-certificate-config create linux --label=<CERT_LABEL> --module=<PKCS11_MODULE_PATH> --slot=<SLOT_ID>` -1. Update the `certificate_config.json` file with details about the certificate (See [Configuration](#certificate-configutation) section for details.) + * **Windows** `$ gcloud auth enterprise-certificate-config create windows --issuer=<CERT_ISSUER> --provider=<PROVIDER> --store=<STORE>` 1. Enable usage of client certificates through gcloud CLI config command: ``` - gcloud config set context_aware/use_client_certificate true + $ gcloud config set context_aware/use_client_certificate true ``` +1. You can now use gcloud to access CBA-protected GCP resources. For example: + ``` + $ gcloud pubsub topics list + ``` + +### Manual Certificate Configuration -1. You can now use gcloud to access GCP resources with mTLS. +ECP relies on the `certificate_config.json` file to read all the metadata information for locating the certificate. +It is stored as a JSON file at the following location on the user's device: -### Certificate Configuration +* **Linux and MacOS**: ~/.config/gcloud/certificate_config.json +* **Windows**: %APPDATA%\gcloud\certificate_config.json -ECP relies on the `certificate_config.json` file to read all the metadata information for locating the certificate. The contents of this JSON file look like the following: +Below are example configurations: #### MacOS (Keychain) @@ -124,11 +128,10 @@ variable. #### Example ``` -export ENABLE_ENTERPRISE_CERTIFICATE_LOGS=1 # Now the -enterprise-certificate-proxy will output logs to stdout. +export ENABLE_ENTERPRISE_CERTIFICATE_LOGS=1 # Now the enterprise-certificate-proxy will output logs to stdout. ``` -## Build binaries +## Building ECP binaries from source For amd64 MacOS, run `./build/scripts/darwin_amd64.sh`. The binaries will be placed in `build/bin/darwin_amd64` folder. @@ -150,6 +153,6 @@ Apache - See [LICENSE](./LICENSE) for more information. [openssl]: https://wiki.openssl.org/index.php/Binaries [keystore]: https://en.wikipedia.org/wiki/Key_management [cloudsdk]: https://cloud.google.com/sdk -[enterprisecert]: https://cloud.google.com/access-context-manager/docs/enterprise-certificates +[enterprisecert]: https://cloud.google.com/beyondcorp-enterprise/docs/enable-cba-enterprise-certificates [zerotrust]: https://cloud.google.com/blog/topics/developers-practitioners/zero-trust-and-beyondcorp-google-cloud |