Oracle Cloud Infrastructure Documentation

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.

Required Permissions

To Create a Pre-Authenticated Request

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

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 to grant user read/write access to objects.
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.

Options

When creating a pre-authenticated request, you have the following options:

  • You can specify the name of a bucket that a pre-authenticated request user has write access to and can upload one or more objects to.
  • You can specify the name of an object that a pre-authenticated request user can read from, write to, or read from and write to.

Scope and Constraints

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

  • Users can't list bucket contents.
  • You can create an unlimited number of pre-authenticated requests.
  • There is no time limit to the expiration date that you can set.
  • You can't edit a pre-authenticated request. If you want to change user access options in response to changing requirements, you must create a new pre-authenticated request.
  • 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.
  • 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, delete, or list pre-authenticated requests using the Console, using the 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 bucket or object specified as the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation and cannot be retrieved later.

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

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/docs/b/par-bucket/o/using-dita-guide.pdf
To get an object
$ curl -X GET <unique-PAR-URL>

For example:

$ curl -X GET https://objectstorage.us-phoenix-1.oraclecloud.com/p/j3DoSvgQHbUaw6ADzHkDlnaqMuXWef_lhTxCiS9ngCw/n/namespace/b/par-bucket/o/using-dita-guide.pdf

Using the Console

To create a pre-authenticated request for a bucket
See Service Limits for a list of applicable limits and instructions for requesting a limit increase.
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  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. Click Create Pre-Authenticated Request.
  6. Provide the following information:

    • Name: The system automatically generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-bucket-20191101-1327.

      If you change this default or any other pre-authenticated request name, use letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

    • Pre-Authenticated Request Target: Select 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 Copy to copy the URL for future reference.

    Note

    The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the bucket or object specified as the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation and cannot be retrieved later.
  9. Click Close.
To create a pre-authenticated request for an object
  1. Open the navigation menu. Under Core Infrastructure, click Object Storage.
  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 you want to create a pre-authenticated request, click the Actions icon (three dots), and then click Create Pre-Authenticated Request.
  6. Provide the following information:

    • Name: The system generates a default, pre-authenticated request name that reflects the current year, month, day, and time, for example par-object-object-name-20191101-1429.

      If you change this default or any other pre-authenticated request name, use letters, numbers, dashes, underscores, and periods. Avoid entering confidential information.

    • Pre-Authenticated Request Target: Select Object.
    • Object Name: The name of the object that you want authenticated by this rule.

    • Access Type: Select one of the following.

      • 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 displays the URL used to access the object.

  8. Click Copy to copy the URL for future reference.

    Note

    The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the bucket or object specified as the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation and cannot be retrieved later.
  9. Click Close.
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. Under Core Infrastructure, click Object Storage.
  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 icon (three dots), 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 a bucket
oci os preauth-request create --namespace <object_storage_namespace> --bucket-name <bucket_name> --name <preauthenticated_request_name> --access-type AnyObjectWrite --time-expires <timestamp>

Note the following:

  • To create a pre-authenticated request for a bucket, use the AnyObjectWrite enum value with the --access-type flag. Pre-authenticated requests for buckets permit writes to the bucket by default.
  • The <timestamp> is required and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.
Note

The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the bucket or object specified as the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation and cannot be retrieved later.
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> -on <object_name_or_null>

The <enum_value> for --access-type is one of the following:

  • ObjectRead (permits read on the object)
  • ObjectWrite (permits writes to the object)
  • ObjectReadWrite (permits reads on and writes to the object)

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

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

Note

The unique URL provided by the system when you create a pre-authenticated request is the only way a user can access the bucket or object specified as the request target. Copy the URL to durable storage. The URL is displayed only at the time of creation and cannot be retrieved later.
To list a pre-authenticated request
oci os preauth-request list --namespace <object_storage_namespace> --bucket-name <bucket_name>
To get a pre-authenticated request
oci os preauth-request get --namespace <object_storage_namespace> --bucket-name <bucket_name> --par-id <preauthenticated_request_id>
To delete a pre-authenticated request
oci os preauth-request delete --namespace <object_storage_namespace> --bucket-name <bucket_name> --par-id <preauthenticated_request_id>