Using Pre-Authenticated Requests

Pre-authenticated requests provide a way to let users access a bucket or an object without having their own credentials, as long as the request creator has permissions to access those objects.

For example, you can create a request that lets an operations support user upload backups to a bucket without owning API keys. Or, you can create a request that lets a business partner update shared data in a bucket without owning API keys.

When you create a pre-authenticated request, a unique URL is generated. Anyone you provide this URL to can access the Object Storage resources identified in the pre-authenticated request, using standard HTTP tools like curl and wget.

Important:

Assess the business requirement for and the security ramifications of pre-authenticated access to a bucket or objects.

A pre-authenticated request URL gives anyone who has the URL access to the targets identified in the request. Carefully manage the distribution of the URL.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

Listing Pre-Authenticated Requests

Use this procedure to obtain information about pre-authenticated requests, such as obtaining the pre-authenticated requests id that you might need for other commands.

Note:

Listing pre-authenticated requests does not display the unique URL provided by the system when you created a pre-authenticated request. The URL is displayed only at the time of creation and cannot be retrieved later.

Using the OCI CLI

• Listing All the Pre-Authenticated Requests in a Bucket

  1. Gather the information you need to run the command.

     • Namespace (see Obtaining the Object Storage Namespace)

     • Bucket name (oci os bucket list), see Listing Buckets

  2. Run the command.

     Syntax (entered on a single line):

     oci os preauth-request list
     --namespace-name <object_storage_namespace> 
     --bucket-name <bucket_name>

     Example:

     oci os preauth-request list \
     --namespace-name examplenamespace  \
     --bucket-name MyBucket
     {
       "data": [
         {
           "access-type": "ObjectRead",
           "id": "5299a6f9-55c7-4805-88ca-b270c9a9e94f",
           "name": "PAR_ObjRead",
           "object-name": "compute.log",
           "time-created": "2021-06-10T20:34:01+00:00",
           "time-expires": "2021-07-30T23:55:00+00:00"
         },
         {
           "access-type": "AnyObjectWrite",
           "id": "783cd56b-9df5-4518-aacf-f523deae5102",
           "name": "PAR-all-objectsRW",
           "object-name": null,
           "time-created": "2021-06-10T20:49:11+00:00",
           "time-expires": "2021-07-30T23:54:59+00:00"
         },
         {
           "access-type": "ObjectRead",
           "id": "2ea48624-16ed-4d81-95ca-b23ea750ed3d",
           "name": "PAR-OS-READ",
           "object-name": "backup.log",
           "time-created": "2021-06-10T21:16:47+00:00",
           "time-expires": "2021-07-30T23:55:00+00:00"
         }
       ]
     }

• Getting the Details for a Specific Pre-Authenticated Request

  1. Gather the information you need to run the command.

     • Namespace (see Obtaining the Object Storage Namespace)

     • Bucket name (oci os bucket list), see Listing Buckets

     • Preauth ID (oci os preauth-request list), see Listing Pre-Authenticated Requests

  2. Run the command.

     Syntax (entered on a single line):

     oci os preauth-request get
     --namespace-name <object_storage_namespace>
     --bucket-name <bucket_name>
     --par-id <preauth-id>

     Example:

     oci os preauth-request get  \
     --namespace-name examplenamespace  \
     --bucket-name MyBucket  \
     --par-id 5299a6f9-55c7-4805-88ca-b270c9a9e94f
     {
       "data": {
         "access-type": "ObjectRead",
         "id": "5299a6f9-55c7-4805-88ca-b270c9a9e94f",
         "name": "PAR_ObjRead",
         "object-name": "compute.log",
         "time-created": "2021-06-10T20:34:01+00:00",
         "time-expires": "2021-07-30T23:55:00+00:00"
       }
     }

Creating a Pre-Authenticated Request for All Objects in a Bucket

Using the OCI CLI

1. Gather the information you need to run the command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Bucket name (oci os bucket list), see Listing Buckets

   • Name for this pre-authenticated request.

   • Access type is one of these items:

     • AnyObjectRead permits reads on all objects in the bucket.

     • AnyObjectWrite permits writes to all objects in the bucket.

     • AnyObjectReadWrite permits reads and writes to all objects in the bucket.

     Note:

     Listing objects in a bucket is denied by default. If the --access-type is AnyObjectRead or AnyObjectReadWrite, you can specify the optional --bucket-listing-action ListObjects parameter when creating the pre-authenticated request that lets users list the objects in the bucket.

   • Time expires is required and must be an RFC 3339 time stamp. For example: 2017-09-01T00:09:51.000+02:00.

2. Run the command.

   Syntax (entered on a single line):

   oci os preauth-request create
   --namespace-name <object_storage_namespace> 
   --bucket-name <bucket_name>
   --name <preauthenticated_request_name> 
   --access-type <access_value>
   --time-expires <timestamp>

   This example creates a pre-authenticated request that allows reads and writes to all objects in the bucket:

    oci os preauth-request create  \
   --namespace-name examplenamespace  \
   --bucket-name MyBucket  \
   --name PAR-all-objectsRW  \
   --access-type AnyObjectWrite  \
   --time-expires '2021-07-30 23:55'
   {
     "data": {
       "access-type": "AnyObjectWrite",
       "access-uri": "/p/KOCRWzqBilJmIsaBbJNelKLWcOxwRLq/n/examplenamespace/b/MyBucket/o/",
       "id": "783cd56b-9df5-4518-aacf-f523deae5102",
       "name": "PAR-all-objectsRW",
       "object-name": null,
       "time-created": "2021-06-10T20:49:11+00:00",
       "time-expires": "2021-07-30T23:54:59+00:00"
     }
   }

3. Important – Copy the access-uri to durable storage.

   The unique access-uri provided by the system is the only way to construct a URL that a user can use to access the bucket or object specified as the request target.

   The access-uri is displayed only at the time of creation and cannot be retrieved later.

4. Construct a URL from the unique access-uri.

   See Constructing the Pre-Authenticated Request URL.

Creating a Pre-Authenticated Request for a Specific Object

Using the OCI CLI

1. Gather the information you need to run the command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Bucket name (oci os bucket list), see Listing Buckets

   • Name for this pre-authenticated request.

   • Access type is one of the following values:

     • AnyObjectRead permits reads on all objects in the bucket.

     • AnyObjectWrite permits writes to all objects in the bucket.

     • AnyObjectReadWrite permits reads and writes to all objects in the bucket.

     Note:

     Listing objects in a bucket is denied by default. If the --access-type is AnyObjectRead or AnyObjectReadWrite, you can specify the optional --bucket-listing-action ListObjects parameter when creating the pre-authenticated request that lets users list the objects in the bucket.

   • Time expires is required and must be an RFC 3339 time stamp. For example: 2017-09-01T00:09:51.000+02:00.

   • Object name, or null

2. Syntax (entered on a single line):

   oci os preauth-request create
   --namespace-name <object_storage_namespace> 
   --bucket-name <bucket_name> 
   --name <preauthenticated_request_name> 
   --access-type <access_value> 
   --time-expires <timestamp> 
   -on <object_name_or_null>

   Example:

   oci os preauth-request create
   --namespace-name examplenamespace  \ 
   --bucket-name MyBucket 
   --name PAR-OS-READ 
   --access-type ObjectRead 
   --time-expires '2021-07-30 23:55' 
   -on compute.log
   
   {
     "data": {
       "access-type": "ObjectRead",
       "access-uri": "/p/eWvgyLcDthhvVUNkVaejymgDTOILHli/n/examplenamespace/b/MyBucket/o/compute.log",
       "id": "2ea48624-16ed-4d81-95ca-b23ea750ed3d",
       "name": "PAR-OS-READ",
       "object-name": "compute.log",
       "time-created": "2021-06-10T21:16:47+00:00",
       "time-expires": "2021-07-30T23:55:00+00:00"
     }
   }

3. Important – Copy the access-uri to durable storage.

   The unique access-uri provided by the system is the only way to construct a URL that a user can use to access the bucket or object specified as the request target.

   The access-uri is displayed only at the time of creation and cannot be retrieved later.

4. Construct a URL from the unique access-uri.

   See Constructing the Pre-Authenticated Request URL.

Constructing the Pre-Authenticated Request URL

After you have a unique access-uri, you can construct the access URL that enables users to access pre-authenticated objects.

1. Construct the URL using this syntax.

   Syntax:

   https://<pca_fqdn><access-uri>

   where:

   • <pca_fqdn>- the fully qualified domain name of your appliance.

   • <access-uri>- the access URI that was obtained from one of these procedures:

     • Creating a Pre-Authenticated Request for All Objects in a Bucket

     • Creating a Pre-Authenticated Request for a Specific Object

   Example:

   https://mypca01.example.com/p/MrxLFkKlFkIlNDhvhcZnrjbUAlsoeah/n/mynamespace/b/my-bucket/o/my-object

Deleting a Pre-Authenticated Request

Using the OCI CLI

1. Gather the information you need to run the command.

   • Namespace (see Obtaining the Object Storage Namespace)

   • Bucket name (oci os bucket list), see Listing Buckets

   • Preauth ID (oci os preauth-request list), see Listing Pre-Authenticated Requests

2. Syntax (entered on a single line):

   oci os preauth-request delete
   --namespace-name <object_storage_namespace> 
   --bucket-name <bucket_name>
   --par-id <preauthenticated_request_id>

   Example:

   oci os preauth-request delete  \
   --namespace-name examplenamespace  \
   --bucket-name MyBucket  \
   --par-id 2ea48624-16ed-4d81-95ca-b23ea750ed3d
   Are you sure you want to delete this resource? [y/N]: y

Listing Objects for Pre-Authenticated Requests

Using the unique request URL, you can use a tool like curl to list, read, and write data using the pre-authenticated request.

Using curl

• Syntax (entered on a single line):

  $ curl -X GET <unique-PAR-URL>

  Example:

  $ curl -X GET    \
  https://objectstorage.us-example-1.example.com/p/CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/examplenamespace/b/MyParBucket/o/
  
  {"objects":[{"name":"InfoWorld DeepDive - Tips  for Git and GitHub Users.pdf"},{"name":"OCI_User_Guide.pdf"},
  {"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf"},{"name":"VPN.png"},{"name":"eventslogreference.htm"},
  {"name":"functionslogreference.htm"},{"name":"glob.txt"},{"name":"loadbalancerreference.htm"},{"name":"objectstoragelogreference.htm"},
  {"name":"servicechanges.html"},{"name":"servicediscovery.dita"},{"name":"serviceessentials.html"},{"name":"servicelogreference.htm"},
  {"name":"services.html"}]}

Uploading an Object Using a Pre-Authenticated Request

Using the unique request URL, you can use a tool like curl to read and write data using the pre-authenticated request.

Using curl

• Syntax (entered on a single line):

  $ curl -X PUT --data-binary '@<local-filename>' <unique-PAR-URL>

  Example:

  $ curl -X PUT    \
  --data-binary '@using-dita-guide.pdf'    \
  https://objectstorage.us-example-1.example.com/p/lnaqMuXWef_lhTxCiS9ngCw/n/examplenamespace/b/MyParBucket/o/using-dita-guide.pdf

Downloading an Object Using a Pre-Authenticated Request

Using the unique request URL, you can use a tool like curl to read and write data using the pre-authenticated request.

Using curl

• Syntax (entered on a single line):

  $ curl -X GET <unique-PAR-URL>

  Example:

  $ curl -X GET    \
  https://objectstorage.example.com/p/tnjDhazP9o6s2KzLyFUxILQzSamEp/n/examplenamespace/b/MyParBucket/o/OCI_User_Guide.pdf 
  '@data.1''@data.2''@data.3'