(opendal) branch main updated: doc: explain GCS authentication options (#4671)

[xu...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal.git


The following commit(s) were added to refs/heads/main by this push:
     new 788d105a2c doc: explain GCS authentication options (#4671)
788d105a2c is described below

commit 788d105a2ca8faa9f393366d7d2306114dba0420
Author: Wang Guan <mo...@gmail.com>
AuthorDate: Sun Jun 2 03:26:41 2024 +0900

    doc: explain GCS authentication options (#4671)
---
 core/src/services/gcs/docs.md | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

diff --git a/core/src/services/gcs/docs.md b/core/src/services/gcs/docs.md
index 83e227e4d2..d818b6bbaf 100644
--- a/core/src/services/gcs/docs.md
+++ b/core/src/services/gcs/docs.md
@@ -18,12 +18,32 @@ This service can be used to:
 - `root`: Set the work directory for backend
 - `bucket`: Set the container name for backend
 - `endpoint`: Customizable endpoint setting
-- `credential`: Credentials string for GCS service OAuth2 authentication
-- `credential_path`: Local path to credentials file for GCS service OAuth2 authentication
+- `credential`: Service Account or External Account JSON, in base64
+- `credential_path`: local path to Service Account or External Account JSON file
+- `service_account`: name of Service Account
 - `predefined_acl`: Predefined ACL for GCS
 - `default_storage_class`: Default storage class for GCS
 
-Refer to public API docs for more information.
+Refer to public API docs for more information. For authentication related options, read on.
+
+## Options to authenticate to GCS
+
+OpenDAL supports the following authentication options:
+
+1. Provide a base64-ed JSON key string with `credential`
+2. Provide a JSON key file at explicit path with `credential_path`
+3. Provide a JSON key file at implicit path
+    - `GcsBackend` will attempt to load Service Account key from [ADC well-known places](https://cloud.google.com/docs/authentication/application-default-credentials).
+4. Fetch access token from [VM metadata](https://cloud.google.com/docs/authentication/rest#metadata-server)
+    - Only works when running inside Google Cloud.
+    - If a non-default Service Account name is required, set with `service_account`. Otherwise, nothing need to be set.
+5. A custom `TokenLoader` via `GcsBuilder.customed_token_loader()`
+
+Notes:
+
+- When a Service Account key is provided, it will be used to create access tokens (VM metadata will not be used).
+- Explicit Service Account key, in json or path, always take precedence over ADC-defined key paths.
+- Due to [limitation in GCS](https://cloud.google.com/storage/docs/authentication/signatures#signing-process), a private key is required to create Pre-signed URL. Currently, OpenDAL only supports Service Account key.
 
 ## Example
 
@@ -44,8 +64,8 @@ async fn main() -> Result<()> {
     // set the working directory root for GCS
     // all operations will happen within it
     builder.root("/path/to/dir");
-    // set the credentials string of service account
-    builder.credential("service account credential");
+    // set the credentials with service account
+    builder.credential("service account JSON in base64");
     // set the predefined ACL for GCS
     builder.predefined_acl("publicRead");
     // set the default storage class for GCS