From 18de4fea460b4c6d8a57e7c130d7b2753e3fab9e Mon Sep 17 00:00:00 2001 From: Leonardo Siracusa Date: Tue, 9 Feb 2021 15:54:37 -0800 Subject: [PATCH] docs: address review comments --- README.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 915db7272..7ef7021a4 100644 --- a/README.md +++ b/README.md @@ -168,12 +168,12 @@ for (Bucket b : storage_service.list().iterateAll()) ### Workload Identity Federation Using workload identity federation, your application can access Google Cloud resources from -Amazon Web Services (AWS), Microsoft Azure or any identity provider that supports OpenID Connect +Amazon Web Services (AWS), Microsoft Azure, or any identity provider that supports OpenID Connect (OIDC). Traditionally, applications running outside Google Cloud have used service account keys to access -Google Cloud resources. Using identity federation, you can allow your workload to impersonate a -service account. This lets you access Google Cloud resources directly, eliminating the maintenance +Google Cloud resources. Using identity federation, your workload can impersonate a service account. +This lets the external workload access Google Cloud resources directly, eliminating the maintenance and security burden associated with service account keys. #### Accessing resources from AWS @@ -189,7 +189,7 @@ configure workload identity federation from AWS. After configuring the AWS provider to impersonate a service account, a credential configuration file needs to be generated. Unlike service account credential files, the generated credential -configuration file will only contain non-sensitive metadata to instruct the library on how to +configuration file contains non-sensitive metadata to instruct the library on how to retrieve external subject tokens and exchange them for service account access tokens. The configuration file can be generated by using the [gcloud CLI](https://cloud.google.com/sdk/). @@ -210,9 +210,9 @@ Where the following variables need to be substituted: - `$AWS_PROVIDER_ID`: The AWS provider ID. - `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate. -This will generate the configuration file in the specified output file. +This generates the configuration file in the specified output file. -You can now [start using the Auth library](#using-external-identities) to call Google Cloud +You can now [use the Auth library](#using-external-identities) to call Google Cloud resources from AWS. #### Access resources from Microsoft Azure @@ -229,7 +229,7 @@ to configure workload identity federation from Microsoft Azure. After configuring the Azure provider to impersonate a service account, a credential configuration file needs to be generated. Unlike service account credential files, the generated credential -configuration file will only contain non-sensitive metadata to instruct the library on how to +configuration file contains non-sensitive metadata to instruct the library on how to retrieve external subject tokens and exchange them for service account access tokens. The configuration file can be generated by using the [gcloud CLI](https://cloud.google.com/sdk/). @@ -250,9 +250,9 @@ Where the following variables need to be substituted: - `$AZURE_PROVIDER_ID`: The Azure provider ID. - `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate. -This will generate the configuration file in the specified output file. +This generates the configuration file in the specified output file. -You can now [start using the Auth library](#using-external-identities) to call Google Cloud +You can now [use the Auth library](#using-external-identities) to call Google Cloud resources from Azure. #### Accessing resources from an OIDC identity provider @@ -267,7 +267,7 @@ to configure workload identity federation from an OIDC identity provider. After configuring the OIDC provider to impersonate a service account, a credential configuration file needs to be generated. Unlike service account credential files, the generated credential -configuration file will only contain non-sensitive metadata to instruct the library on how to +configuration file contains non-sensitive metadata to instruct the library on how to retrieve external subject tokens and exchange them for service account access tokens. The configuration file can be generated by using the [gcloud CLI](https://cloud.google.com/sdk/). @@ -301,9 +301,9 @@ Where the following variables need to be substituted: - `$POOL_ID`: The workload identity pool ID. - `$OIDC_PROVIDER_ID`: The OIDC provider ID. - `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate. -- `$PATH_TO_OIDC_ID_TOKEN`: The file path where the OIDC token will be retrieved from. +- `$PATH_TO_OIDC_ID_TOKEN`: The file path used to retrieve the OIDC token. -This will generate the configuration file in the specified output file. +This generates the configuration file in the specified output file. **URL-sourced credentials** For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC token. @@ -336,12 +336,12 @@ Where the following variables need to be substituted: - `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`. -You can now [start using the Auth library](#using-external-identities) to call Google Cloud +You can now [use the Auth library](#using-external-identities) to call Google Cloud resources from an OIDC provider. #### Using External Identities -External identities (AWS, Azure and OIDC-based providers) can be used with +External identities (AWS, Azure, and OIDC-based providers) can be used with `Application Default Credentials`. In order to use external identities with Application Default Credentials, you need to generate the JSON credentials configuration file for your external identity as described above. Once generated, store the path to this file in the @@ -351,8 +351,8 @@ as described above. Once generated, store the path to this file in the export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json ``` -The library can now automatically choose the right type of client and initialize credentials from -the context provided in the configuration file. +The library can now choose the right type of client and initialize credentials from the context +provided in the configuration file. ```java GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault(); @@ -364,7 +364,7 @@ HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCre HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter); HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url)); -JsonObjectParser parser = new JsonObjectParser(JacksonFactory.getDefaultInstance()); +JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance()); request.setParser(parser); HttpResponse response = request.execute();