Generally speaking, managing Object Storage programmatically, using the API/SDL/CLI is the most efficient means of managing your object storage data. However, it’s also true that using API/SDK/CLI may not always be practical, especially when you need a quick and painless way to share data with a third party. Pair that with the pre-requisite of creating BMCS credentials just to share data, and there you have it….. The recipe for operational pain!
Pre-Authenticated Requests (PARs) are the perfect antidote to this operational pain!
With PARs, you can share and upload object storage data without programmatic interfaces or BMCS IAM accounts. When you create a PAR, a unique PAR URL is generated. Anyone you provide this URL to can access the resources identified in the pre-authenticated request, using standard HTTP tools like cURL and wget. You can define PARs on both buckets and objects. Bucket PARs can be used to write data into a specific bucket, however object PARs can be used both to read and write data. When creating a PAR you need to specify a PAR name, the resource (object or bucket), the authorized operations (read, write, read/write) and the PAR expiration date. Listing objects stored in a bucket is not supported via PARs.
PAR access is tied to the credentials of the BMCS IAM user that creates the PAR. Under the covers, every time a PAR is used, the request is authenticated with the PAR creator’s credentials. The PAR expiration date determines the length of time the PAR is valid. Once a PAR expires, it can no longer be used. You can theoretically create a PAR that ‘never’ expires by setting an expiration date that is way out in the future. Only BMCS IAM users, who have the PAR_MANAGE permission, are authorized to create PARs. In addition, the PAR creator also needs to have permission to access the resource (bucket or object) they are intending to create the PAR on.
Sample PAR – A ‘read’ PAR defined on object ‘Oracle.jpg’ stored in the bucket ‘PAR_Demo’ looks something like this:
Note that unlike other competitive offerings that also support the notion of temporary URLs, PARs have an inherent advantage in that these are created server side. You can continue to manage PARs, long after these are created. The PAR creator is always in full control of the PAR, no matter what. The PARs can be listed by bucket, and deleted at will. Deleting PARs immediately revokes a user’s privilege to access the data associated with the PAR. You can create a PAR, using the service console, the CLI or the SDK.
Steps to create a PAR URL, using the UI
From the BMCS service console, navigate to the Storage –> Object Storage menu and select the bucket that you want to create a PAR on. In the example below, I’ve chose the bucket ‘PAR_demo . I’ll create a ‘read’ PAR on the object ‘Oracle.jpg’. Select the bucket and then click ‘Pre-Authenticated Requests’, displayed in the left panel below.
Enter the PAR name, the name of the object, the operation you’d like to authorize, and the expiration date for the PAR. Click “Create Pre-Authenticated Request” to create the PAR.
The system then displays the PAR that you can share with others:
Once a PAR is created, it is listed in the bucket details page in the order in which it was created. Once a PAR is deleted, the PAR URL will immediately stop working.
Steps to create a PAR URL, using the CLI
Download and install the BMCS CLI. Write the following CLI command:
$ bmcs os preauth-request create –ns<namespace> -bn <bucketname> --name <PAR_Name> --access-type ObjectRead --time-expires 2017-10-02T15:00:00.05Z -on <object name>
You can now take the string "/p/wQAej-jmILCxSUIC3bVPM58xUCcOpXfFtPmmOX_g/n/internalrachnathusoo/b/PAR_Demo/o/Oracle.jpg” and append it to the base URL “ https://objectstorage.us-phoenix-1.oraclecloud.com” to get the PAR URL https://objectstorage.us-phoenix-1.oraclecloud.com/p/nzYzV3LXqYs38Zf17T8HPaOYJCGnZ0Wc/n/namespace/b/PAR_Demo/o/Oracle.jpg
To get help with other PAR CLI commands, type the following command on the prompt:
$ bmcs os preauth-request
Reading or writing data using PARs
You can use standard HTTP tools to read and write data, using the PAR URL:
Using cURL or wget to read Oracle.jpg
Using cURL to write an file using a PAR
If you create a ‘write’ PAR on Oracle.jpg , you can use the following CURL command to write data to this PAR:
curl -X PUT -d 'samplefile.jpg ' -v https://objectstorage.us-phoenix-1.oraclecloud.com/p/Z7k6ia9rVGieZiYxU1gCDws57GIs9S42f5k0BE/n/namespace/b/bucket/o/Oracle.jpg
Using Curl to write (upload) multiple files to the bucket ‘PAR_Demo’, using a PAR defined on the bucket
curl -X PUT -d 'SampleFile1.jpg' https://objectstorage.us-phoenix-1.oraclecloud.com/p/5MGn_owaSgU-FPg2Jl_nMaeq23YlXCI0W3Od6o/n/namespace/b/PAR_Demo/o/SampleFile1.jpg
curl -X PUT -d 'SampleFile2.jpg' https://objectstorage.us-phoenix-1.oraclecloud.com/p/5MGn_owaSgU-FPg2Jl_nMaeq23YlXCI0W3Od6o/n/namespace/b/PAR_Demo/o/SampleFile2.jpg
curl -X PUT -d 'SampleFile3.jpg' https://objectstorage.us-phoenix-1.oraclecloud.com/p/5MGn_owaSgU-FPg2Jl_nMaeq23YlXCI0W3Od6o/n/namespace/b/PAR_Demo/o/SampleFile3.jpg
As you can see, creating, managing, and sharing data using PARs is simple and straightforward. In conclusion, PARs are a fairly secure means of sharing data with a third party. However you need to be extra careful when sharing the URL, so that only the intended user gets access to the PAR. As we demonstrated, once created, anyone who has access to the PAR URL can access the specified object storage resource. There is no way to determine what users are actually accessing the PAR through the URL.
For additional information you can review the PAR FAQs. Good luck and share responsibly!
Director, Product Management
Oracle Bare Metal Cloud Team