docs: Update README with X.509 feature details.

Author: nbayati

README.md

@@ -367,8 +367,9 @@ 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), a local server (URL-sourced credentials), or a X.509 
+certificate and private-key combination (X.509 certificate-sourced credentials).
 
 **File-sourced credentials**
 For file-sourced credentials, a background process needs to be continuously refreshing the file
@@ -435,6 +436,71 @@ 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 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 and must be renewed to maintain access.
+
+The library constructs a subject token by creating a JSON array containing the base64-encoded leaf certificate, followed by any intermediate certificates from a provided trust chain.
+
+#### 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 `gcloud 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.
+
+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**