From 0164a4e686f578e9620cf42355016151c3d7375d Mon Sep 17 00:00:00 2001 From: Manoj Ghosh Date: Mon, 13 Feb 2023 11:30:31 -0800 Subject: [PATCH] add more documentation around oci authentication ways --- docs/content/oracleobjectstorage.md | 104 ++++++++++++++++++++++++++-- 1 file changed, 98 insertions(+), 6 deletions(-) diff --git a/docs/content/oracleobjectstorage.md b/docs/content/oracleobjectstorage.md index 8c28f2898..75b3103b0 100644 --- a/docs/content/oracleobjectstorage.md +++ b/docs/content/oracleobjectstorage.md @@ -5,13 +5,12 @@ versionIntroduced: "v1.60" --- # {{< icon "fa fa-cloud" >}} Oracle Object Storage - [Oracle Object Storage Overview](https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/objectstorageoverview.htm) [Oracle Object Storage FAQ](https://www.oracle.com/cloud/storage/object-storage/faq/) -Paths are specified as `remote:bucket` (or `remote:` for the `lsd` -command.) You may put subdirectories in too, e.g. `remote:bucket/path/to/dir`. +Paths are specified as `remote:bucket` (or `remote:` for the `lsd` command.) You may put subdirectories in +too, e.g. `remote:bucket/path/to/dir`. ## Configuration @@ -87,7 +86,7 @@ Enter a value. Press Enter to leave empty. endpoint> Option config_file. -Path to OCI config file +Full Path to OCI config file Choose a number from below, or type in your own string value. Press Enter for the default (~/.oci/config). 1 / oci configuration file location @@ -136,6 +135,99 @@ List the contents of a bucket rclone ls remote:bucket rclone ls remote:bucket --max-depth 1 +### OCI Authentication Provider + +OCI has various authentication methods. To learn more about authentication methods please refer [oci authentication +methods](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdk_authentication_methods.htm) +These choices can be specified in the rclone config file. + +Rclone supports the following OCI authentication provider. + + User Principal + Instance Principal + Resource Principal + No authentication + +#### Authentication provider choice: User Principal +Sample rclone config file for Authentication Provider User Principal: + + [oos] + type = oracleobjectstorage + namespace = id34 + compartment = ocid1.compartment.oc1..aaba + region = us-ashburn-1 + provider = user_principal_auth + config_file = /home/opc/.oci/config + config_profile = Default + +Advantages: +- One can use this method from any server within OCI or on-premises or from other cloud provider. + +Considerations: +- you need to configure user’s privileges / policy to allow access to object storage +- Overhead of managing users and keys. +- If the user is deleted, the config file will no longer work and may cause automation regressions that use the user's credentials. + +#### Authentication provider choice: Instance Principal +An OCI compute instance can be authorized to use rclone by using it's identity and certificates as an instance principal. +With this approach no credentials have to be stored and managed. + +Sample rclone configuration file for Authentication Provider Instance Principal: + + [opc@rclone ~]$ cat ~/.config/rclone/rclone.conf + [oos] + type = oracleobjectstorage + namespace = idfn + compartment = ocid1.compartment.oc1..aak7a + region = us-ashburn-1 + provider = instance_principal_auth + +Advantages: + +- With instance principals, you don't need to configure user credentials and transfer/ save it to disk in your compute + instances or rotate the credentials. +- You don’t need to deal with users and keys. +- Greatly helps in automation as you don't have to manage access keys, user private keys, storing them in vault, + using kms etc. + +Considerations: + +- You need to configure a dynamic group having this instance as member and add policy to read object storage to that + dynamic group. +- Everyone who has access to this machine can execute the CLI commands. +- It is applicable for oci compute instances only. It cannot be used on external instance or resources. + +#### Authentication provider choice: Resource Principal +Resource principal auth is very similar to instance principal auth but used for resources that are not +compute instances such as [serverless functions](https://docs.oracle.com/en-us/iaas/Content/Functions/Concepts/functionsoverview.htm). +To use resource principal ensure Rclone process is started with these environment variables set in its process. + + export OCI_RESOURCE_PRINCIPAL_VERSION=2.2 + export OCI_RESOURCE_PRINCIPAL_REGION=us-ashburn-1 + export OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM=/usr/share/model-server/key.pem + export OCI_RESOURCE_PRINCIPAL_RPST=/usr/share/model-server/security_token + +Sample rclone configuration file for Authentication Provider Resource Principal: + + [oos] + type = oracleobjectstorage + namespace = id34 + compartment = ocid1.compartment.oc1..aaba + region = us-ashburn-1 + provider = resource_principal_auth + +#### Authentication provider choice: No authentication +Public buckets do not require any authentication mechanism to read objects. +Sample rclone configuration file for No authentication: + + [oos] + type = oracleobjectstorage + namespace = id34 + compartment = ocid1.compartment.oc1..aaba + region = us-ashburn-1 + provider = no_auth + +## Options ### Modified time The modified time is stored as metadata on the object as @@ -536,8 +628,8 @@ Remove unfinished multipart uploads. This command removes unfinished multipart uploads of age greater than max-age which defaults to 24 hours. -Note that you can use -i/--dry-run with this command to see what it -would do. +Note that you can use --interactive/-i or --dry-run with this command to see what +it would do. rclone backend cleanup oos:bucket/path/to/object rclone backend cleanup -o max-age=7w oos:bucket/path/to/object