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.
You can configure an S3 bucket to allow read-only, anonymous access. This approach requires no credentials but limits users to non-modifying operations.
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.
It isn’t possible to create access keys for UIDs in an Active Directory environment that has POSIX extensions enabled. However, it is possible to use Active Directory identity identifiers (SIDs, UPNs, and so on).
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 uses a cryptographically secure source, certified according to FIPS 140-2 requirements, to derive secret access keys.
- Because access keys are cluster-local, you can't use an access key for an identity in one Qumulo cluster on a different Qumulo cluster.
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.
Because (unlike secret access keys) your access key IDs aren’t a cryptographic secret, Qumulo Core can log and display access key IDs. After Qumulo Core initially creates your secret access keys, it never logs or displays them again. If you lose your secret access key, it isn’t possible to recover it and you must create a new access key pair.
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.
- To facilitate key rotation, each user identity can have at most two S3 access key pairs associated with it. It is a good practice to delete a user's old access key after you create a new one and test that the new key works.
- If you revoke an access key pair, it isn't possible to restore it. Before you revoke an access key pair, ensure that no critical applications depend on it.
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 the PRIVILEGE_S3_BUCKETS_WRITE
privilege.
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
Currently, it isn’t possible to associate an S3 access key with a POSIX group ID (GID).
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
.
After Qumulo Core initially creates your secret access keys, it never logs or displays them again. If you lose your secret access key, it isn’t possible to recover it and you must create a new access key pair.
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
.
After Qumulo Core initially creates your secret access keys, it never logs or displays them again. If you lose your secret access key, it isn’t possible to recover it and you must create a new access key pair.
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.
Qumulo Core doesn’t list access keys in any particular order. To sort keys according to fields such as
creation_time
or owner
you must process or filter the response.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.
To restrict the number of returned results, up to the maximum of 10,000 access keys (this is the default limit), include the optional
limit
query parameter in the request.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
To be able to create access keys for a user in a joined AD domain, the user must exist within the domain’s base DN.
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