This section explains how to create and manage credentials that S3 API actions in Qumulo Core require to access file system resources, such as access key pairs that sign requests.

i% include note.html content=”You can configure an S3 bucket to allow read-only, anonymous access. This approach requires no credentials but limits users to non-modifying operations. For more information, see To Enable Anonymous Access to S3 Buckets by Using the qq CLI.” %}

Prerequisites

Managing S3 access keys requires the following role-based access control (RBAC) privileges:

  • PRIVILEGE_S3_BUCKETS_WRITE: Create and delete S3 access keys

  • PRIVILEGE_S3_BUCKETS_READ: List S3 access keys

How S3 Access Keys Work in Qumulo Core

An identity is a single principal from an identity provider (IdP). Examples of identities include SMB security identifiers (SIDs), Active Directory user principal names (UPNs), POSIX user identifiers (UIDs), and local users in a Qumulo cluster.

An access key (or access key pair) is comprised of an S3 access key ID and an S3 secret access key.

  • The access key ID is the public component of an S3 access key pair. It identifies the user that performs an S3 request.

  • The secret access key (or secret key) is the private component of an S3 access key pair. The client uses the secret access key to sign requests and the server uses the secret access key to validate request signatures.

Qumulo Core creates an access key pair whenever an authorized user requests it. For more information, see Creating S3 Access Keys for a Qumulo Cluster.

The way in which Qumulo Core access keys let you access your Qumulo cluster makes the process similar to the way in which IAM Access Keys let you access Amazon S3 resources. For this reason, applications that access objects stored in a Qumulo cluster can use the Qumulo S3 API similarly to the native Amazon S3 API.

How S3 Access Keys work with Identities

An S3 access key doesn’t grant any additional permissions. It associates an S3 API request with a specific identity that the Qumulo cluster knows.

When Qumulo Core processes a request, it evaluates permissions by using the Qumulo ACL (QACL) mechanism that operates like the access control list (ACL) mechanism that all file system protocols use. When the QACL grants or denies permissions to an associated identity, it also grants or denies the same permissions to the request being processed.

For more information, see Managing Access to S3 Buckets in a Qumulo Cluster.

How Qumulo Core Stores S3 Access Keys

To authenticate S3 API requests, Qumulo Core retrieves existing access key pairs that it stores securely as configuration metadata in your Qumulo cluster. Qumulo Core encrypts secret access keys on disk and holds decrypted secret access keys in memory only while it processes a request.

S3 Access Key Lifecycle in Qumulo Core

Qumulo Core doesn’t limit how long you can use an access key pair after you create it. Your system administrators must take responsibility for using the Qumulo Core REST API or qq CLI to view the creation dates for access keys and revoke any pair at their discretion.

For more information, see Listing S3 Access Keys for a Qumulo Cluster.

Creating S3 Access Keys for a Qumulo Cluster

To make S3 API requests to a Qumulo cluster as a specific user, you must create an S3 access key pair for that user identity by using the Qumulo REST API or qq CLI.

To create S3 access keys, you must have an administrator account or have .

To Create an Access Key by Using the qq CLI

To create an S3 access key for a particular user identity, run the qq s3_create_access_key command and specify an identity. For example:

$ qq s3_create_access_key my_identity

You can specify an identity by using:

  • A name, optionally qualified with a domain prefix:

    • ad:MY_NAME

    • AD\MY_NAME

    • local:MY_NAME

    • MY_NAME

  • An Active Directory Security Identifier. For example: SID:S-1-1-0

  • A Qumulo auth ID, Qumulo Core’s common representation for identities, in the form of a numeric identifier. For example: auth_id:513

The following is example output.

{
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "creation_time": "2022-12-12T21:37:53.553457928Z",
  "owner": {
    "auth_id": "501",
    "domain": "LOCAL",
    "gid": null,
    "name": "guest",
    "sid": "S-0-1-23-4567890123-456789012-345678901-234",
    "uid": null
  },
  "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

In this example, the access key id is 000000000001fEXAMPLE and the secret access key is TEIT4liMZ8A32iI7JXmqIiLWp5co/jmkjEXAMPLE.

To Create an S3 Access Key by Using the Qumulo Core REST API

Send a POST request to the /v1/s3/access-keys/ endpoint with the following body. You must include at least one of the following keys:

  • auth_id

  • sid

  • uid

For example:

{
  "user": {
    "sid": "S-0-1-23-4567890123-456789012-345678901-234"
  }
}

The following is example output.

{
  "access_key_id": "AKIAIOSFODNN7EXAMPLE",
  "creation_time": "2022-12-12T21:37:53.553457928Z",
  "owner": {
    "auth_id": "501",
    "domain": "LOCAL",
    "gid": null,
    "name": "guest",
    "sid": "S-0-1-23-4567890123-456789012-345678901-234",
    "uid": null
  },
  "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}

In this example, the access key id is 000000000001fEXAMPLE and the secret access key is TEIT4liMZ8A32iI7JXmqIiLWp5co/jmkjEXAMPLE.

Listing S3 Access Keys for a Qumulo Cluster

You can list every S3 access key that your Qumulo cluster knows, along with the identities associated with the key and the key creation times, by using the Qumulo REST API or qq CLI.

To list S3 access keys, you must have the PRIVILEGE_S3_BUCKETS_READ privilege.

To List S3 Access Keys by Using the qq CLI

  • To list the S3 access keys that your Qumulo cluster knows, run the qq s3_list_access_keys :

    The following is example output. All times are in the UTC time zone.

    access_key_id         owner  creation_time
====================  =====  ==============================
000000000001fEXAMPLE  Guest  2022-12-12T21:37:53.553457928Z

  • For JSON output, use the --json flag.

    The following is example output. The command returns a single JSON object that contains the combined responses from calls to the /v1/s3/access-keys/ Qumulo Core REST API endpoint.

{
  "entries": [
    {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "creation_time": "2022-12-12T21:37:53.553457928Z",
      "owner": {
        "auth_id": "501",
        "domain": null,
        "gid": null,
        "name": null,
        "sid": null,
        "uid": null
      }
    },
    ...
  ],
  "paging": {
    "next": null
  }
}

To List S3 Access Keys by Using the Qumulo Core REST API

To list the S3 access keys that your Qumulo cluster knows, send a GET request to the /v1/s3/access-keys/ endpoint.

The following is example output. The entries list contains the access keys, limited to the first 10,000. The paging.next field contains the URI to which you can send a GET request to retrieve the next page of access keys. By making GET requests with all returned paging.next values, you can iterate over all of the access keys in the cluster.

{
  "entries": [
    {
      "access_key_id": "AKIAIOSFODNN7EXAMPLE",
      "creation_time": "2022-12-12T21:37:53.553457928Z",
      "owner": {
        "auth_id": "501",
        "domain": null,
        "gid": null,
        "name": null,
        "sid": null,
        "uid": null
      }
    },
    ...
  ],
  "paging": {
    "next": null
  }
}

Revoking S3 Access Keys for a Qumulo Cluster

To revoke an S3 access key, you must delete the access key from your Qumulo cluster. You can delete an S3 access key by using the Qumulo REST API or qq CLI.

To revoke an access key, you must have the PRIVILEGE_S3_BUCKETS_WRITE privilege.

To Delete an S3 Access Key by Using the qq CLI

Run the qq s3_delete_access_key command and specify the access key ID. For example:

$ qq s3_delete_access_key \
  --id 000000000001fEXAMPLE

To Delete an S3 Access Key by Using the Qumulo Core REST API

Send a DELETE request to the /v1/s3/access-keys/<access-key-id> Qumulo Core REST API endpoint and specify the access key ID.

Configuring Active Directory (AD) for S3

For users that exist in an AD domain that has a trust relationship with the joined domain, you must append that domain’s base DN to the base DN in your Qumulo cluster’s AD configuration.

To append the trusted base DN to the base DN in use—with a semicolon (;) separating the two—use the Qumulo Core Web UI or the qq ad_reconfigure command. For example:

$ qq ad_reconfigure \
  --base-dn 'CN=Users,DC=joined_domain,DC=example,DC=com;CN=Users,DC=trusted_domain,DC=example,DC=com'

For more information, see Configuring Cross-Domain Active Directory Trusts