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.
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
andOBJECT_OVERWRITE
permissions in addition toPAR_MANAGE
. - If you are creating a pre-authenticated request for read/write access to
objects in a bucket, you need
OBJECT_READ
,OBJECT_CREATE
, andOBJECT_OVERWRITE
permissions in addition toPAR_MANAGE
.
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
andPUT
objects with the prefix name specified in the request. Trying toGET
orPUT
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.
- 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.
- The URL generated when you create a pre-authenticated request for an object with a prefix does not contain the prefix by default. The user must manually add the prefix to the URL to be able to access the object.
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.
$ 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
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
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
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 "
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.-H
opc-meta-<name>:<value>
"
$ 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'
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.
$ 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
You can override the response headers in the PAR GET requests by using the following query parameters:
httpResponseContentDisposition
httpResponseCacheControl
httpResponseContentType
httpResponseContentLanguage
httpResponseContentEncoding
httpResponseExpires
For example:
Default URL (shows inline) - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt
Download and save with default filename - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt?httpResponseContentDisposition=attachment
Download and save with custom filename - https://objectstorage.us-phoenix-1.oraclecloud.com/p/bDh0EOiY_C0K0NYn8YIhC_fgVOj96BM8S6YApdmlr7pwv4Xuie-6IiLbF1eQdcWi/n/bmcostests/b/bucket-20220302-1236/o/example.txt?httpResponseContentDisposition=attachment%3B%20filename%3Ddownload.txt
Using the Console
- Open the navigation menu and click Storage. Under Object Storage, click Buckets.
- Choose the compartment where the bucket is.
- Click the bucket name.
- Click Pre-Authenticated Requests under Resources to display the list of existing pre-authenticated requests.
- Click Create Pre-Authenticated Request.
- 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.
-
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.
-
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. - Click Close.
Alternatively, you can create a pre-authenticated request for all objects in a bucket from the Console bucket list page.
- Open the navigation menu and click Storage. Under Object Storage, click Buckets.
- On the bucket list page, click the Actions menu to the right of the bucket, and then click Create Pre-Authenticated Request.
- Provide the information to complete the dialog.
- Open the navigation menu and click Storage. Under Object Storage, click Buckets.
- Choose the compartment where the bucket is.
-
Click the bucket name.
- Click Objects under Resources to display the list of objects.
- For the object that you want to create a pre-authenticated request, click the Actions menu, and then click Create Pre-Authenticated Request.
- 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.
-
-
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.
-
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. - Click Close.
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.
- Open the navigation menu and click Storage. Under Object Storage, click Buckets.
- Choose the compartment where the bucket is.
- Click the bucket name.
- Click Pre-Authenticated Requests under Resources to display the list of existing pre-authenticated requests.
- Click Create Pre-Authenticated Request.
- Select the required Pre-Authenticated Request Target of Objects with prefix to properly set the context for the other fields in the dialog.
- 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.
-
-
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.
-
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.
- The URL generated when you create a pre-authenticated request for an object with a prefix does not contain the prefix by default. The user must manually add the prefix to the URL to be able to access the object.
- Click Close.
Alternatively, you can create a pre-authenticated request for objects with a specific prefix from the Console bucket list page.
- Open the navigation menu and click Storage. Under Object Storage, click Buckets.
- 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.
- Change the required Pre-Authenticated Request Target to Objects with prefix.
- Provide the information to complete the dialog.
To copy the ID for a pre-authenticated request to the clipboard, do the following:
- Open the navigation menu and click Storage. Under Object Storage, click Buckets.
- Choose the compartment where the bucket is.
- Click the bucket name.
- Click Pre-Authenticated Requests under Resources to display the list of pre-authenticated requests.
-
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.
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 bucketAnyObjectWrite
permits writes to all objects in the bucketAnyObjectReadWrite
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.
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"
}
}
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.
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 readsObjectWrite
permits object writesObjectReadWrite
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
.
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"
}
}
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'
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 prefixAnyObjectWrite
permits writes to objects with the specified prefixAnyObjectReadWrite
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.
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"
}
}
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"}
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"
}
]
}
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"
}
}
oci os preauth-request delete --namespace <object_storage_namespace> --bucket-name <bucket_name> --par-id <preauthenticated_request_id>
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
Using the API
For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.
Use the following operations to work with pre-authenticated requests: