docs: Update README with X.509 feature details (#1790)

* docs: Update README with X.509 feature details.

* Address the review comments

Author: nbayati

README.md

@@ -44,6 +44,7 @@ information, refer to [documentation](https://cloud.google.com/docs/authenticati
       * [Accessing resources from AWS](#accessing-resources-from-aws)
       * [Accessing resources from Azure](#access-resources-from-microsoft-azure)
       * [Accessing resources from an OIDC identity provider](#accessing-resources-from-an-oidc-identity-provider)
+      * [Accessing resources using X.509 certificate-sourced credentials](#accessing-resources-using-x509-certificate-sourced-credentials)
       * [Accessing resources using Executable-sourced credentials](#using-executable-sourced-credentials-with-oidc-and-saml)
       * [Accessing resources using a custom supplier for OIDC or SAML](#using-a-custom-supplier-with-oidc-and-saml)
       * [Accessing resources using a custom supplier with AWS](#using-a-custom-supplier-with-aws)
@@ -367,10 +368,12 @@ configuration file contains non-sensitive metadata to instruct the library on ho
 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/).
 
-For OIDC providers, the Auth library can retrieve OIDC tokens either from a local file location
-(file-sourced credentials) or from a local server (URL-sourced credentials).
+For OIDC providers, the Auth library can retrieve OIDC tokens from a local file 
+([file-sourced credentials](#file-sourced-credentials)), a local server 
+([URL-sourced credentials](#url-sourced-credentials)), or a X.509 
+certificate and private-key combination (X.509 certificate-sourced credentials).
 
-**File-sourced credentials**
+#### File-sourced credentials
 For file-sourced credentials, a background process needs to be continuously refreshing the file
 location with a new OIDC token prior to expiration. For tokens with one hour lifetimes, the token
 needs to be updated in the file every hour. The token can be stored directly as plain text or in
@@ -401,7 +404,7 @@ Where the following variables need to be substituted:
 
 This generates the configuration file in the specified output file.
 
-**URL-sourced credentials**
+#### URL-sourced credentials
 For URL-sourced credentials, a local server needs to host a GET endpoint to return the OIDC token.
 The response can be in plain text or JSON. Additional required request headers can also be
 specified.
@@ -435,6 +438,73 @@ request to `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`.
 You can now [use the Auth library](#using-external-identities) to call Google Cloud
 resources from an OIDC provider.
 
+### Accessing resources using X.509 certificate-sourced credentials
+For more information, see the [official documentation](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates).
+
+For X.509 certificate-sourced credentials, the authentication library uses an X.509 certificate and private key to prove your application's identity. The certificate has a built-in expiration date, which is defined in the certificate itself, and must be renewed to maintain access.
+
+#### Prerequisites: Generating Configuration Files for X.509 Federation
+To configure X.509 certificate-sourced credentials, you need to generate two separate configuration files: a primary **credential configuration file** and a **certificate configuration file**. The primary credential configuration file contains the necessary metadata for authentication, and it points to the certificate configuration file, which contains the paths to the X.509 certificate, private key, and trust chain.
+
+The [`gcloud iam workload-identity-pools create-cred-config`](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config) command can be used to create both.
+
+The location where the certificate configuration file is created depends on whether you use the `--credential-cert-configuration-output-file` flag.
+
+**Default Behavior (Recommended)**
+
+If you omit the `--credential-cert-configuration-output-file` flag, gcloud creates the certificate configuration file at a default, well-known location that the auth library can automatically discover. This is the simplest approach for most use cases. The default credential configuration file is named `config.json` and the default certificate configuration file is named `certificate_config.json`.
+
+Example Command (Default Behavior):
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+    projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID \
+    --service-account $SERVICE_ACCOUNT_EMAIL \
+    --credential-cert-path "$PATH_TO_CERTIFICATE" \
+    --credential-cert-private-key-path "$PATH_TO_PRIVATE_KEY" \
+    --credential-cert-trust-chain-path "$PATH_TO_TRUST_CHAIN" \
+    --output-file /path/to/config.json
+```
+
+Where the following variables need to be substituted:
+
+- `$PROJECT_NUMBER`: The Google Cloud project number.
+- `$POOL_ID`: The workload identity pool ID.
+- `$PROVIDER_ID`: The provider ID.
+- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
+- `$PATH_TO_CERTIFICATE`: The file path where your leaf X.509 certificate is located.
+- `$PATH_TO_PRIVATE_KEY`: The file path where the corresponding private key for the leaf certificate is located.
+- `$PATH_TO_TRUST_CHAIN`: The file path of the X.509 certificate trust chain file. This file should be a PEM-formatted file containing any intermediate certificates required to complete the trust chain between the leaf certificate and the trust store configured in the Workload Identity Federation pool. The leaf certificate is optional in this file.
+
+This command results in:
+
+- `/path/to/config.json`: Created at the path you specified. This file will contain `"use_default_certificate_config": true` to instruct clients to look for the certificate configuration at the default path.
+- `certificate_config.json`: Created at the default gcloud configuration path, which is typically `~/.config/gcloud/certificate_config.json` on Linux and macOS, or `%APPDATA%\gcloud\certificate_config.json` on Windows.
+
+**Custom Location Behavior**
+
+If you need to store the certificate configuration file in a non-default location, use the `--credential-cert-configuration-output-file` flag.
+
+Example Command (Custom Location):
+
+```bash
+gcloud iam workload-identity-pools create-cred-config \
+    projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID \
+    --service-account $SERVICE_ACCOUNT_EMAIL \
+    --credential-cert-path "$PATH_TO_CERTIFICATE" \
+    --credential-cert-private-key-path "$PATH_TO_PRIVATE_KEY" \
+    --credential-cert-trust-chain-path "$PATH_TO_TRUST_CHAIN" \
+    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
+    --output-file /path/to/config.json
+```
+
+This command results in:
+
+- `/path/to/config.json`: Created at the path you specified. This file will contain a `"certificate_config_location"` field that points to your custom path.
+- `cert_config.json`: Created at `/custom/path/cert_config.json`, as specified by the flag.
+
+You can now [use the Auth library](#using-external-identities) to call Google Cloud resources with X.509 certificate-sourced credentials.
+
 #### Using Executable-sourced credentials with OIDC and SAML
 
 **Executable-sourced credentials**