Using Pre-Authenticated Requests

Pre-authenticated requests provide a way to let users access a bucket or an object without having their own credentials. Users continue to have access to the bucket or object as long as the creator of the request has permissions to access those resources. 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 access all your quarterly financial reports 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 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.

Required Permissions

To Create a Pre-Authenticated Request

To create or manage pre-authenticated requests, you need PAR_MANAGE permission to the target bucket.

While you only need PAR_MANAGE permission to create a pre-authenticated request, you must also have the appropriate permissions for the access type that you are granting. For example:

  • If you are creating a pre-authenticated request for uploading objects to a bucket, you need OBJECT_CREATE and OBJECT_OVERWRITE permissions in addition to PAR_MANAGE.
  • If you are creating a pre-authenticated request for read/write access to objects in a bucket, you need OBJECT_READ, OBJECT_CREATE, and OBJECT_OVERWRITE permissions in addition to PAR_MANAGE.
Important

If the creator of a pre-authenticated request is deleted or loses the required permissions after they created the request, the request will no longer work.

To Use a Pre-Authenticated Request

Permissions of the pre-authenticated request creator are checked each time you use a pre-authenticated request. The pre-authenticated request no longer works when any of the following occurs:

  • Permissions of the pre-authenticated request creator have changed.
  • User who created the pre-authenticated request is deleted.
  • Federated user who created the pre-authenticated request has lost the user capabilities that they had when they created the request.
  • Pre-authenticated request has expired or has been deleted.

Options

You can create a pre-authenticated request that grants read, write, or read/write access to one of the following:

  • All objects in the bucket.
  • A specific object in the bucket.
  • All objects in the bucket that have a specified prefix.

For requests that apply to multiple objects, you can also decide whether you want to let users list those objects.

Scope and Constraints

Understand the following scope and constraints regarding pre-authenticated requests:

  • You can create an unlimited number of pre-authenticated requests.
  • A pre-authenticated request created for all objects in a bucket lets request users upload any number of objects to the bucket.
  • Expiration date is required, but has no limits. You can set them as far out in the future as you want.
  • You can't edit a pre-authenticated request. If you want to change user access options or enable object listing in response to changing requirements, you must create a new pre-authenticated request.
  • By default, pre-authenticated requests for a bucket or objects with prefix cannot be used to list objects. You can explicitly enable object listing when you create a pre-authenticated request.
  • When you create a pre-authenticated request that limits scope to objects with a specific prefix, request users can only GET and PUT objects with the prefix name specified in the request. Trying to GET or PUT an object without the specified prefix or with a different prefix fails.
  • The target and actions for a pre-authenticated request are based on the creator's permissions. The request is not, however, bound to the creator's account login credentials. If the creator's login credentials change, a pre-authenticated request is not affected.
  • Deleting a pre-authenticated request revokes user access to the associated bucket or object.
  • Pre-authenticated requests cannot be used to delete buckets or objects.
  • You cannot delete a bucket that has a pre-authenticated request associated with that bucket or with an object in that bucket.

Working with Pre-Authenticated Requests

You can create, list, or delete pre-authenticated requests using the Console, CLI, or by using an SDK to access the API.

Important

The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, is not stored in Object Storage, and cannot be retrieved later.

Using the unique request URL, you can use a tool like curl to read and write data using the pre-authenticated request. Object Storage now supports writing large files using multipart uploads with pre-authenticated requests.

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

For example:

$ curl -X PUT --data-binary '@using-dita-guide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/j3DoSvgQHbUaw6ADzHkDlnaqMuXWef_lhTxCiS9ngCw/n/MyNamespace/b/MyParBucket/o/using-dita-guide.pdf
To put an object with custom metadata

You can also provide custom metadata for any object using opc-meta-<name>:<value> headers.

$ curl -X PUT -H "opc-meta-<name>:<value>" --data-binary '@<local-filename>' <unique-PAR-URL>

For example:

$ curl -X PUT -H "opc-meta-version:2020May" PUT --data-binary '@CorporateTerminologyUsageGuide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/71LzRt_V8LVT7BVLbeQOB5KAx67AxzeKXwJ8mIA5dN0WheYH39a7KiY2UXnUBhaX/n/MyNamespace/b/MyParBucket/o/CorporateTerminologyUsageGuide.pdf
To put a large object

Multipart uploads accommodate objects that are too large for a single upload operation. We recommend that you use multipart uploads to upload objects larger than 100 MiB. The maximum size for an uploaded object is 10 TiB. Object parts must be no larger than 50 GiB. Using multipart uploads, you have the flexibility of pausing between the uploads of individual parts, and resuming the upload when your schedule and resources allow.

Step 1: To direct Object Storage to create a multipart upload, you simply include the header opc-multipart: true in the PUT command.

$ curl -X PUT -H "opc-multipart:true" <unique-PAR-URL>

For example:

$ curl -X PUT -H "opc-multipart:true" https://objectstorage.us-phoenix-1.oraclecloud.com/p/j3DoSvgQHbUaw6ADzHkDlnaqMuXWef_lhTxCiS9ngCw/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
The PUT with the opc-multipart: true header returns an access URI to use to upload parts and commit the multipart upload, for example:
{"namespace":"MyNamespace","bucket":"MyParBucket","object":"OCI_User_Guide.pdf","uploadId":"b5bb4079-9d50-ac59-182e-4d133a962382","timeCreated":"2021-03-05T14:48:53.738Z","storageTier":"Standard","accessUri":"/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/"}

Step 2: Use the access URI together with the Object Storage hostname for the target region to upload parts, specifying the part number at the end of the URI. For example, to upload an object in three parts, issue the following PUT commands:

$ curl -X PUT --data-binary '@data.1' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/1
$ curl -X PUT --data-binary '@data.2' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/2
$ curl -X PUT --data-binary '@data.3' https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/3

Step 3: To commit the multipart upload, use the POST command with the access URI. For example:

$ curl -X POST https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/

You can delete all parts of an uncommitted or failed multipart upload using the DELETE command with the access URI. For example:

$ curl -X DELETE https://objectstorage.us-phoenix-1.oraclecloud.com/p/8dFlNPzKOl2s9R6EGCxtdRKr-zSG45X2BA1k63dIm_SMrgg_HMzg9FblpOWEs5Lh/n/MyNamespace/b/MyParBucket/u/OCI_User_Guide.pdf/id/b5bb4079-9d50-ac59-182e-4d133a962382/

You can also provide custom metadata for any object using opc-meta- headers. The "-H opc-meta-<name>:<value>" is only needed on the first pre-authenticated request that creates the multipart upload, not on each individual part. See To put an object with custom metadata for more information.

To get an object
$ curl -X GET <unique-PAR-URL>

For example:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/MR7rGASetBbu4L1R5ZH91meUZJjVkOGmd4rtnjDhazP9o6s2KzLyFUxILQzSamEp/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
'@data.1''@data.2''@data.3'
To get a list of objects

For pre-authenticated requests that apply to multiple objects, the request creator can optionally let you list objects.

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

For example:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/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"},{"name":"udx-1494-lifecycle-rule-glob.pdf"}]}

By default, the object list returns only the names of the objects. Optionally, you can use the fields query parameter to also include the size (object size in bytes), etag, md5, timeCreated (object creation date and time), timeModified (object modification date and time), storageTier, and archivalState fields. Specify the value of this parameter as a comma-separated, case-insensitive list of those field names that you want to include in the object list. For example:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/?fields="name,etag,timeCreated,md5,timeModified,storageTier,archivalState"
{"objects":[{"name":"InfoWorld DeepDive - Tips  for Git and GitHub Users.pdf","timeCreated":"2021-04-01T14:27:13.039Z","timeModified":"2021-04-01T14:27:27.552Z","etag":"e5032a35-07d7-476f-88aa-a95c5d07f0d9","storageTier":"Standard","md5":"3OPjerv2zKJdf9fzFeP9BQ=="},{"name":"OCI_User_Guide.pdf","timeCreated":"2021-04-01T14:27:20.359Z","timeModified":"2021-04-02T23:18:01.299Z","etag":"0dd28308-b821-47e7-9685-111eedef1c5c","storageTier":"Standard","md5":"/2+fTemSy7CsR00OnFK87Q=="},{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf","timeCreated":"2021-04-01T14:27:12.228Z","timeModified":"2021-04-01T14:27:21.302Z","etag":"1948d01b-9611-4a79-a9dd-f5b24888c0bc","storageTier":"Standard","md5":"JIdR+kCzQNkl0riH08Ktpw=="},{"name":"VPN.png","timeCreated":"2021-04-01T14:27:11.943Z","timeModified":"2021-04-01T14:27:12.047Z","etag":"b4f20050-e268-42e5-8980-29f6a972b6bf","storageTier":"Standard","md5":"aWFjq5fe+hsDT/x5cWhasA=="},{"name":"eventslogreference.htm","timeCreated":"2021-04-01T14:27:10.725Z","timeModified":"2021-04-01T14:27:10.746Z","etag":"84362592-0a18-438d-8773-7dcc702103aa","storageTier":"Standard","md5":"As+3syaEbvMhPm8fM+DSAw=="},{"name":"functionslogreference.htm","timeCreated":"2021-04-01T14:27:10.865Z","timeModified":"2021-04-01T14:27:10.900Z","etag":"4d494efa-5d48-491a-84ba-254be2aa8549","storageTier":"Standard","md5":"lt28WcIiqKklMS5p2LbECQ=="},{"name":"glob.txt","timeCreated":"2021-04-05T16:12:31.925Z","timeModified":"2021-04-05T16:12:31.952Z","etag":"c330ce8c-4c61-4342-9ac5-4bc0fd846944","storageTier":"Standard","md5":"BeMbbI+uOOGzmFA/NXwwxQ=="},{"name":"loadbalancerreference.htm","timeCreated":"2021-04-01T14:27:11.480Z","timeModified":"2021-04-01T14:27:11.574Z","etag":"522a3b1d-f736-4e30-9b5d-feed3867912d","storageTier":"Standard","md5":"u2GP2ngLVEq9xUAykRg2ug=="},{"name":"objectstoragelogreference.htm","timeCreated":"2021-04-01T14:27:11.416Z","timeModified":"2021-04-01T14:27:11.479Z","etag":"fbf7a035-7b80-4c91-a932-53bf0917bef9","storageTier":"Standard","md5":"skstBGw3YcHBomI6X/YwEA=="},{"name":"servicechanges.html","timeCreated":"2021-04-01T14:27:11.702Z","timeModified":"2021-04-01T14:27:11.716Z","etag":"016df222-128d-4e7f-a191-b5c0a5dbc7e0","storageTier":"Standard","md5":"sVzYaODHww3Qw1jwbtj7SA=="},{"name":"servicediscovery.dita","timeCreated":"2021-04-02T17:16:04.134Z","timeModified":"2021-04-02T17:16:04.149Z","etag":"7997226d-e2ba-460a-be75-97436dcb30e8","storageTier":"Standard","md5":"I/ZjF5rcoaJXH6abpbDPag=="},{"name":"serviceessentials.html","timeCreated":"2021-04-01T14:27:11.700Z","timeModified":"2021-04-01T14:27:11.737Z","etag":"687d0914-19c7-4ff6-8ceb-90ab0bbd1fc1","storageTier":"Standard","md5":"HSf0uMVHxFCuVr/I5insxQ=="},{"name":"servicelogreference.htm","timeCreated":"2021-04-01T14:27:11.767Z","timeModified":"2021-04-01T14:27:11.775Z","etag":"240f2d71-da38-461c-a821-506b85b7e6e7","storageTier":"Standard","md5":"jxyWxK9z8OW0zsozadNRkQ=="},{"name":"services.html","timeCreated":"2021-04-01T14:27:11.780Z","timeModified":"2021-04-01T14:27:11.913Z","etag":"6e570928-a5b2-4e49-8e54-22186825350a","storageTier":"Standard","md5":"fDuH2Y7LDAafjlyUCQZohQ=="},{"name":"udx-1494-lifecycle-rule-glob.pdf","timeCreated":"2021-04-01T14:27:12.044Z","timeModified":"2021-04-01T14:27:12.686Z","etag":"a92174a2-cad3-4239-b4c9-48f2abd4dd8c","storageTier":"Standard","md5":"4ltcJZgQ80sNz8RHu7TJlQ=="}]}

In addition to fields, pre-authenticated requests support all other ListObjects query parameters and list pagination.

To get metadata from an object
$ curl --head <unique-PAR-URL>

For example:

$ curl --head https://objectstorage.us-phoenix-1.oraclecloud.com/p/MR7rGASetBbu4L1R5ZH91meUZJjVkOGmd4rtnjDhazP9o6s2KzLyFUxILQzSamEp/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
HTTP/1.1 200 OK
accept-ranges: bytes
Content-Length: 27
opc-multipart-md5: AgQlttlYM7ya/tH0Fosu9A==-3
last-modified: Fri, 05 Mar 2021 15:15:44 GMT
etag: 9b9093ab-bdc6-49af-b261-b2d1d111d952
version-id: d3346446-e1f3-46e3-97e5-ee3c8e57ee30
storage-tier: Standard
Content-Type: application/x-www-form-urlencoded
date: Thu, 18 Mar 2021 22:11:11 GMT
opc-request-id: phx-1:odm8FLV-LC7yR7sskUL955sjFjOqaKrQ-cO3JbGhSbcwYcovlRa2QtABQPfeW_Q_
x-api-id: native
access-control-allow-origin: *
access-control-allow-methods: POST,PUT,GET,HEAD,DELETE,OPTIONS
access-control-allow-credentials: true
access-control-expose-headers: accept-ranges,access-control-allow-credentials,access-control-allow-methods,access-control-allow-origin,content-length,content-type,date,etag,last-modified,opc-client-info,opc-multipart-md5,opc-request-id,storage-tier,version-id,x-api-id

Using the Console

To create a pre-authenticated request for all objects in a bucket
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment where the bucket is.
  3. Click the bucket name.
  4. Click Pre-Authenticated Requests under Resources to display the list of existing pre-authenticated requests.
  5. Click Create Pre-Authenticated Request.
  6. Provide the following information:
    • Name: Required. The system automatically generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-bucket-20210330-1643.

      If you change this default name, use only letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

    • Pre-Authenticated Request Target: Required. Bucket is selected by default, however, you can select a different target.
    • Access Type: Select one of the following types:
      • Permit object reads (the default)
      • Permit object writes
      • Permit object reads and writes
    • Enable Object Listing: Select this option if you want to also let pre-authenticated request users list the objects in the bucket.
    • Expiration: Accept the one week, system-generated expiration date or use the date and time editor to use a different expiration date and time.
  7. Click Create Pre-Authenticated Request.

    After a request is created, the Pre-Authenticated Request Details dialog box displays the URL used to access the bucket.

  8. Click the copy icon to the right of the URL and paste the URL somewhere in durable storage for future reference.

    Important

    The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, is not stored in Object Storage, and cannot be retrieved later.
  9. Click Close.
Tip

Alternatively, you can create a pre-authenticated request for all objects in a bucket from the Console bucket list page.
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. On the bucket list page, click the Actions menu to the right of the bucket, and then click Create Pre-Authenticated Request.
  3. Provide the information to complete the dialog.
To create a pre-authenticated request for a specific object
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment where the bucket is.
  3. Click the bucket name.

  4. Click Objects under Resources to display the list of objects.
  5. For the object that you want to create a pre-authenticated request, click the Actions menu, and then click Create Pre-Authenticated Request.
  6. Provide the following information:
    • Name: Required. The system automatically generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-object-20210330-1654.

      If you change this default name, use only letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

    • Pre-Authenticated Request Target: Required. Object is selected by default, however, you can select a different target.
    • Object Name: The name of the object that you are creating the pre-authenticated request for is displayed. You cannot change the name of the object.
    • Access Type: Select one of the following types:

      • Permit read on the object
      • Permit writes to the object
      • Permit reads on and writes to the object
    • Expiration: Accept the one week, system-generated expiration date or use the date and time editor to a different expiration date and time.
  7. Click Create Pre-Authenticated Request.

    After a request is created, the Pre-Authenticated Request Details dialog box displays the URL used to access the bucket.

  8. Click the copy icon to the right of the URL and paste the URL somewhere in durable storage for future reference.

    Important

    The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, is not stored in Object Storage, and cannot be retrieved later.
  9. Click Close.
To create a pre-authenticated request for objects with a specific prefix

When you create a pre-authenticated request with a prefix, you are limiting the scope of the request to only those objects with that prefix.

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment where the bucket is.
  3. Click the bucket name.
  4. Click Pre-Authenticated Requests under Resources to display the list of existing pre-authenticated requests.
  5. Click Create Pre-Authenticated Request.
  6. Select the required Pre-Authenticated Request Target of Objects with prefix to properly set the context for the other fields in the dialog.
  7. Provide the following information:
    • Name: Required. The system automatically generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-object-prefix-20210330-1723.

      If you change this default name, use only letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

    • Prefix: Required. Prefix string to match on to specify the objects that the pre-authenticated request applies to:
      • You can specify a prefix that includes one or more forward slashes (/) to match on object names that simulate a hierarchy or a directory structure.
      • You can specify a prefix string without a delimiter to match on the left-most characters of the object name.

      See Object Naming Using Prefixes and Hierarchies for details.

    • Access Type: Select one of the following types:
      • Permit object reads (the default)
      • Permit object writes
      • Permit object reads and writes
    • Enable Object Listing: Select this option if you want to also let pre-authenticated request users list the prefixed objects.
    • Expiration: Accept the one week, system-generated expiration date or use the date and time editor to use a different expiration date and time.
  8. Click Create Pre-Authenticated Request.

    After a request is created, the Pre-Authenticated Request Details dialog box displays the URL used to access the bucket.

  9. Click the copy icon to the right of the URL and paste the URL somewhere in durable storage for future reference.

    Important

    The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation, is not stored in Object Storage, and cannot be retrieved later.
  10. Click Close.
Tip

Alternatively, you can create a pre-authenticated request for objects with a specific prefix from the Console bucket list page.
  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. On the bucket list page, click the Actions menu to the right of the bucket that you want to specify prefixed objects, and then click Create Pre-Authenticated Request.
  3. Change the required Pre-Authenticated Request Target to Objects with prefix.
  4. Provide the information to complete the dialog.
To copy a pre-authenticated request ID

To copy the ID for a pre-authenticated request to the clipboard, do the following:

  1. Open the navigation menu and click Storage. Under Object Storage, click Buckets.
  2. Choose the compartment where the bucket is.
  3. Click the bucket name.
  4. Click Pre-Authenticated Requests under Resources to display the list of pre-authenticated requests.
  5. For the pre-authenticated request ID that you want to copy, click the Actions menu, and then click Copy Pre-Authenticated Request ID.

    The ID for the selected pre-authentication request is copied to the clipboard.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

To create a pre-authenticated request for all objects in a bucket
oci os preauth-request create --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <preauthenticated_request_name> --access-type <enum_value> --time-expires <timestamp> [--bucket-listing-action ListObjects]

Avoid entering confidential information in the <preauthenticated_request_name>.

The <enum_value> for --access-type is one of the following when creating a pre-authenticated request for all objects in a bucket:

  • 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

<timestamp> is required and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

Listing objects 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.

For example, to create a pre-authenticated request that allows reads and writes to all objects in the bucket named MyParBucket:
oci os preauth-request create --namespace MyNamespace --bucket-name MyParBucket --name MyAllObjectsReadWritePAR --access-type AnyObjectReadWrite --time-expires="2022-11-21T23:00:00+00:00" --bucket-listing-action ListObjects
{  "data": {
    "access-type": "AnyObjectReadWrite",
    "access-uri": "/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/",
    "bucket-listing-action": "ListObjects",
    "id": "QgT6f1skUMbXDhpXKQ4BRX9u7ci8AAJ7f9OGzgdEkNJ3XQmHzeN/kDhLEbN2HvPn",
    "name": "MyAllObjectsReadWritePAR",
    "object-name": null,
    "time-created": "2021-04-02T22:25:27.322000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}
Important

The access-uri provided by the system when you create a pre-authenticated request is the key element of the URL you need to construct to provide user access to the target bucket. Copy the access-uri to durable storage. The access-uri is displayed only at the time of creation and cannot be retrieved later.

The unique pre-authenticated request URL provided to users for the previous example is constructed as follows:

https://objectstorage.<region_identifier>.oraclecloud.com<access-uri>

See About Regions and Availability Domains for the list of valid region identifiers.

For example, here is the complete URL for the request that allows reads and writes to all objects in the bucket named MyParBucket:

https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/

Here is an example of using curl to PUT an object using the pre-authenticated request that allows reads and writes to all objects in the bucket named MyParBucket and has listing objects enabled:

$ curl -X PUT --data-binary '@edit-lifecycle-rules.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/edit-lifecycle-rules.pdf

Here is an example of using curl to GET objects using the same pre-authenticated request:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/2WOshPVWv9uqIqy6abokChGEXYdCZ8l75CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/MyNamespace/b/MyParBucket/o/
{"objects":[{"name":"InfoWorld DeepDive - Tips  for Git and GitHub Users.pdf"},{"name":"OCISG_README.txt"},{"name":"OCI_User_Guide.pdf"},{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf"},{"name":"VPN.png"},{"name":"eventslogreference.htm"},{"name":"flowlogreference.htm"},{"name":"functionslogreference.htm"},{"name":"glob.txt"},{"name":"loadbalancerreference.htm"},{"name":"objectstoragelogreference.htm"},{"name":"replication.txt"},{"name":"troubleshooting.txt"},{"name":"udx-1494-lifecycle-rule-glob.pdf"}]}

Notice the GET lists the recent PUT for edit-lifecycle-rules.pdf and all other objects in the bucket. Optionally, you can use the fields query parameter to also include the size (object size in bytes), etag, md5, timeCreated (object creation date and time), timeModified (object modification date and time), storageTier, and archivalState fields. See To get a list of objects for more details.

To create a pre-authenticated request for an object
oci os preauth-request create --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <preauthenticated_request_name> --access-type <enum_value> -time-expires <timestamp> --object-name <object_name

Avoid entering confidential information in the pre-authenticated request name.

The <enum_value> for --access-type is one of the following when creating a pre-authenticated request for an object:

  • ObjectRead permits object reads
  • ObjectWrite permits object writes
  • ObjectReadWrite permits both object reads and writes

The <timestamp> is required and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

For example, to create a pre-authenticated request that allows reads and writes to an object named OCI_User_Guide.pdf in the bucket named MyParBucket:
oci os preauth-request create --namespace <object_storage_namespace> --bucket-name MyParBucket --name MyObjectReadWritePAR --access-type ObjectReadWrite --object-name OCI_User_Guide.pdf --time-expires="2022-11-21T23:00:00+00:00"
{  "data": {
    "access-type": "ObjectReadWrite",
    "access-uri": "/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf",
    "bucket-listing-action": null,
    "id": "vNObHUdqwf7pfCq9pup/LlMLTLxBt2N2OCKrGwimLFOoJlVfxj/dlESbxyd54vpf:OCI_User_Guide.pdf",
    "name": "MyObjectReadWritePAR",
    "object-name": "OCI_User_Guide.pdf",
    "time-created": "2021-04-01T14:37:26.869000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}
Important

The access-uri provided by the system when you create a pre-authenticated request is the key element of the URL you need to construct to provide user access to the target object. Copy the access-uri to durable storage. The access-uri is displayed only at the time of creation and cannot be retrieved later.

The unique pre-authenticated request URL provided to users for the previous example is constructed as follows:

https://objectstorage.<region_ID>.oraclecloud.com<access-uri>

For example, here is the complete URL for the request that allows reads and writes to an object named OCI_User_Guide.pdf in the bucket named MyParBucket:

https://objectstorage.us-phoenix-1.oraclecloud.com/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf

Here is an example of using curl to PUT an object using the pre-authenticated request that allows reads and writes to the target object named OCI_User_Guide.pdf in the bucket named MyParBucket:

$ curl -X PUT --data-binary '@OCI_User_Guide.pdf' https://objectstorage.us-phoenix-1.oraclecloud.com/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf

Here is an example of using curl to GET the target object using the same pre-authenticated request:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/v0YC_6i3NamyrKlIds0SKnWUMQLw_PFolSyGCpjVUJ6h_A1tnkXJ9VRcuQZTgjRa/n/MyNamespace/b/MyParBucket/o/OCI_User_Guide.pdf
'@OCI_User_Guide.pdf'
To create a pre-authenticated request for objects with a specific prefix

When you create a pre-authenticated request with a prefix, you are limiting the scope of the request to only those objects with that prefix.

oci os preauth-request create --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <preauthenticated_request_name> --access-type <enum_value> --object-name="<prefix>" --time-expires <timestamp> [--bucket-listing-action ListObjects]

Avoid entering confidential information in the <preauthenticated_request_name>.

The <enum_value> for --access-type is one of the following when creating a pre-authenticated request for all objects in a bucket:

  • AnyObjectRead permits reads on objects with the specified prefix
  • AnyObjectWrite permits writes to objects with the specified prefix
  • AnyObjectReadWrite permits both reads and writes to objects with the specified prefix

<timestamp> is required and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

Specify the prefix to match on in the --object-name parameter:

  • You can specify a prefix that includes one or more forward slashes (/) to match on object names that simulate a hierarchy or a directory structure.
  • You can specify a prefix string without a delimiter to match on the left-most characters of the object name.

Listing objects 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.

For example, to create a pre-authenticated request that allows reads and writes to objects with the prefix service in the bucket named MyParBucket:
oci os preauth-request create --namespace MyNamespace --bucket-name MyParBucket --name PrefixedObjectsReadWritePAR --access-type AnyObjectReadWrite --object-name service --time-expires "2022-11-21T23:00:00+00:00" --bucket-listing-action ListObjects
{  "data": {
    "access-type": "AnyObjectReadWrite",
    "access-uri": "/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/",
    "bucket-listing-action": "ListObjects",
    "id": "YOExDlFsNYBNEwF8Uo4aK8WHiz59enVQm1aID+4cxFobgcaofVbZkg371rxK+6Vb",
    "name": "PrefixedObjectsReadWritePAR",
    "object-name": "service",
    "time-created": "2021-04-01T15:35:40.609000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}
Important

The access-uri provided by the system when you create a pre-authenticated request is the key element of the URL you need to construct to provide user access to the target objects. Copy the access-uri to durable storage. The access-uri is displayed only at the time of creation and cannot be retrieved later.

The unique pre-authenticated request URL provided to users for the previous example is constructed as follows:

https://objectstorage.<region_identifier>.oraclecloud.com<access-uri>

See About Regions and Availability Domains for the list of valid region identifiers.

For example, here is the complete URL for the request that allows reads and writes to objects with the prefix service in the bucket named MyParBucket:

https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/

When you create a pre-authenticated request that limits the scope to objects with a specific prefix, request users can only GET and PUT objects with the prefix name specified in the request. Trying to GET or PUT an object without or with a different prefix fails.

Here is an example of using curl to PUT an object using the pre-authenticated request that allows reads and writes to objects with the prefix service in the bucket named MyParBucket:

$ curl -X PUT --data-binary '@servicediscovery.dita' https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/servicediscovery.dita

Here is an example of using curl to GET objects using the same pre-authenticated request:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/
{"objects":[{"name":"servicechanges.html"},{"name":"servicediscovery.dita"},{"name":"serviceessentials.html"},{"name":"servicelogreference.htm"},{"name":"services.html"}]}

Notice the GET lists the recent PUT for servicediscovery.dita and all other objects with a service prefix. Optionally, you can use the fields query parameter to also include the size (object size in bytes), etag, md5, timeCreated (object creation date and time), timeModified (object modification date and time), storageTier, and archivalState fields. See To get a list of objects for more details.

Here is another example of using curl to PUT an object using the same pre-authenticated request. The request fails because the object does not have a service prefix:

$ curl -X PUT --data-binary '@objectstoragelogreference.htm' https://objectstorage.us-phoenix-1.oraclecloud.com/p/l04eqXvxQ5HcnrXkWS8Kdf4mS812KLDyG_dbArXa8hDdHssXTKiUD0w2HNCEDS4W/n/MyNamespace/b/MyParBucket/o/objectstoragelogreference.htm
{"code":"NotAuthenticated","message":"PAR does not exist"}
To list pre-authenticated requests

You can list all the pre-authenticated requests that are associated with a particular bucket and the objects in that bucket.

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

For example:

oci os preauth-request list --namespace MyNamespace --bucket-name MyParBucket
{
  "data": [
    {
      "access-type": "AnyObjectReadWrite",
      "bucket-listing-action": "ListObjects",
      "id": "1G9pfj8elWI0COPtQUmoQayRmYegDrTWjBskI5BixeGY7k5cPHr1BKdFzgEt3OEG",
      "name": "PrefixedObjectsReadWritePAR",
      "object-name": "service",
      "time-created": "2021-04-02T23:52:21.590000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    },
    {
      "access-type": "AnyObjectReadWrite",
      "bucket-listing-action": "ListObjects",
      "id": "N5Fim23jXHBnAtWBo7FOCOTdXwAZgXRJD1FoDs1S8BD0qhYegO0eHF5prVkPkiVM",
      "name": "MyAllObjectsReadWritePAR",
      "object-name": null,
      "time-created": "2021-04-01T14:13:59.659000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    },
    {
      "access-type": "ObjectReadWrite",
      "bucket-listing-action": null,
      "id": "I2Z3qm0rnYiJ5HSTvSCVu8+BqOmy1lXD1dNreBk3eM5VHLdWyIU3xkDTjBqAagoF:OCI_User_Guide.pdf",
      "name": "MyObjectReadWritePAR",
      "object-name": "OCI_User_Guide.pdf",
      "time-created": "2021-04-01T15:27:02.467000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    },
    {
      "access-type": "AnyObjectReadWrite",
      "bucket-listing-action": "ListObjects",
      "id": "QgT6f1skUMbXDhpXKQ4BRX9u7ci8AAJ7f9OGzgdEkNJ3XQmHzeN/kDhLEbN2HvPn",
      "name": "MyAllObjectsReadWritePAR",
      "object-name": null,
      "time-created": "2021-04-02T22:25:27.322000+00:00",
      "time-expires": "2022-11-21T23:00:00+00:00"
    }
  ]
}
To get a pre-authenticated request
oci os preauth-request get --namespace <object_storage_namespace> --bucket-name <bucket_name> --par-id <preauthenticated_request_id>

For example:

oci os preauth-request get --namespace MyNamespace --bucket-name MyParBucket --par-id YOExDlFsNYBNEwF8Uo4aK8WHiz59enVQm1aID+4cxFobgcaofVbZkg371rxK+6Vb
{
  "data": {
    "access-type": "AnyObjectReadWrite",
    "bucket-listing-action": "ListObjects",
    "id": "YOExDlFsNYBNEwF8Uo4aK8WHiz59enVQm1aID+4cxFobgcaofVbZkg371rxK+6Vb",
    "name": "PrefixedObjectsReadWritePAR",
    "object-name": "service",
    "time-created": "2021-04-01T15:35:40.609000+00:00",
    "time-expires": "2022-11-21T23:00:00+00:00"
  }
}
To delete a pre-authenticated request
oci os preauth-request delete --namespace <object_storage_namespace> --bucket-name <bucket_name> --par-id <preauthenticated_request_id>
For example:
oci os preauth-request delete --namespace MyNamespace --bucket-name MyParBucket --par-id YOExDlFsNYBNEwF8Uo4aK8WHiz59enVQm1aID+4cxFobgcaofVbZkg371rxK+6Vb
Are you sure you want to delete this resource? [y/N]: y