Protocols S3 services svm.uuid users endpoint overview

09/11/2024 Contributors

Overview

An S3 user account is created on the S3 server. Buckets that are created for the server are associated with that user (as the owner of the buckets). The creation of the user account involves generating a pair of keys "access" and "secret". These keys are shared with clients (by the administrator out of band) who want to access the S3 server. The access_key is sent in the request and it identifies the user performing the operation. The client or server never send the secret_key over the wire. Only the access_key can be retrieved from a GET operation. The secret_key along with the access_key is returned from a POST operation and from a PATCH operation if the administrator needs to regenerate the keys. If the user is part of active-directory, the user name takes the format "user@fully_qualified_domain_name".

Examples

Retrieving S3 user configurations for a particular SVM

# The API:
/api/protocols/s3/services/{svm.uuid}/users

# The call:
curl -X GET "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users?fields=*&return_records=true" -H "accept: application/hal+json"

# The response:
{
"records": [
  {
    "svm": {
      "uuid": "db2ec036-8375-11e9-99e1-0050568e3ed9",
      "name": "vs1",
      "_links": {
        "self": {
          "href": "/api/svm/svms/db2ec036-8375-11e9-99e1-0050568e3ed9"
        }
      }
    },
    "name": "user-1",
    "comment": "S3 user",
    "access_key": "FAKEACCESSKEYFAKEAC1",
    "key_time_to_live": "PT3H5M",
    "key_expiry_time": "2023-11-13T23:28:03+05:30",
    "id": 3,
    "keys": [
      {
        "id": 1,
        "access_key": "FAKEACCESSKEYFAKEAC1",
        "time_to_live": "PT3H5M",
        "expiry_time": "2023-11-13T23:28:03+05:30"
      },
      {
        "id": 2,
        "access_key": "FAKEACCESSKEYFAKEAC2",
        "time_to_live": "PT6H3M2S",
        "expiry_time": "2023-11-13T23:24:41+05:30"
      }
    ],
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-1"
      }
    }
  },
  {
    "svm": {
      "uuid": "db2ec036-8375-11e9-99e1-0050568e3ed9",
      "name": "vs1",
      "_links": {
        "self": {
          "href": "/api/svm/svms/db2ec036-8375-11e9-99e1-0050568e3ed9"
        }
      }
    },
    "name": "user-2",
    "comment": "s3-user",
    "access_key": "C87S021Q59JJAAQNJP7R",
    "id": 2,
    "keys": [
      {
        "id": 1,
        "access_key": "C87S021Q59JJAAQNJP7R",
      }
    ],
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2"
      }
    }
  }
],
"num_records": 2,
"_links": {
  "self": {
    "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users?fields=*&return_records=true"
  }
}
}

Retrieving the user configuration of a specific S3 user

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X GET "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-1" -H "accept: application/hal+json"

# The response:
{
"svm": {
  "uuid": "db2ec036-8375-11e9-99e1-0050568e3ed9",
  "name": "vs1",
  "_links": {
    "self": {
      "href": "/api/svm/svms/db2ec036-8375-11e9-99e1-0050568e3ed9"
    }
  }
},
"name": "user-1",
"comment": "s3-user",
"access_key": "JJJA3240AD5ZTSHXNC35",
"key_time_to_live": "P6DT1H5M",
"key_expiry_time": "2023-02-20T10:04:31Z",
"id": 3,
"keys": [
  {
    "id": 1,
    "access_key": "JJJA3240AD5ZTSHXNC35",
    "time_to_live": "PT3H5M",
    "expiry_time": "2023-11-13T23:28:03+05:30"
  },
  {
    "id": 2,
    "access_key": "FAKEACCESSKEYFAKEAC2",
    "time_to_live": "PT6H3M2S",
    "expiry_time": "2023-11-13T23:24:41+05:30"
  }
],
"_links": {
  "self": {
    "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-1"
  }
}
}

Creating an S3 user configuration

# The API:
/api/protocols/s3/services/{svm.uuid}/users

# The call:
curl -X POST "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"name\": \"user-1\"}"

# The response:
HTTP/1.1 201 Created
Date: Fri, 31 May 2019 09:34:25 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Location: /api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-1
Content-Length: 244
Content-Type: application/json
{
"num_records": 1,
"records": [
  {
    "name": "user-1",
    "access_key": "JJJA3240AD5ZTSHXNC36",
    "secret_key": "_n8NAqU3A8TN73698j1uJ2YA7oxZ_Va6q4ETMB47"
  }
]
}

Creating an S3 user configuration with key expiration configuration

# The API:
/api/protocols/s3/services/{svm.uuid}/users

# The call:
curl -X POST "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"comment\": \"S3 user3\", \"key_time_to_live\": \"P6DT1H5M\", \"name\": \"user-3\"}"

# The response:
HTTP/1.1 201 Created
Date: Tue, 14 Feb 2023 08:59:31 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors: 'self'
Location: /api/protocols/s3/services/6573ac2b-ab66-11ed-b53d-005056bb4b9b/users/user-3
Content-Length: 337
Content-Type: application/hal+json
Vary: Origin
{
"num_records": 1,
"records": [
  {
    "name": "user-3",
    "access_key": "JJJA3240AD5ZTSHXNC35",
    "secret_key": "OXx6J_GkTc94Xx91cYrNBar_OT3BY6lWOHI_HSR5",
    "key_expiry_time": "2023-06-16T12:08:38Z",
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/6573ac2b-ab66-11ed-b53d-005056bb4b9b/users/user-3"
      }
    }
  }
]
}

Creating an S3 user configuration with a key expiration configuration and where the user is part of Active directory.

# The API:
/api/protocols/s3/services/{svm.uuid}/users

# The call:
curl -X POST "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"comment\": \"S3 user3\", \"key_time_to_live\": \"P6DT1H5M\", \"name\": \"user-3@domain1.com\"}"

# The response:
HTTP/1.1 201 Created
Date: Tue, 14 Feb 2023 08:59:31 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors: 'self'
Location: /api/protocols/s3/services/6573ac2b-ab66-11ed-b53d-005056bb4b9b/users/user-3%40domain1.com
Content-Length: 337
Content-Type: application/hal+json
Vary: Origin
{
"num_records": 1,
"records": [
  {
    "name": "user-3@domain1.com",
    "access_key": "JJJA3240AD5ZTSHXNC35",
    "secret_key": "OXx6J_GkTc94Xx91cYrNBar_OT3BY6lWOHI_HSR5",
    "key_expiry_time": "2023-06-16T12:08:38Z",
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/6573ac2b-ab66-11ed-b53d-005056bb4b9b/users/user-3%40domain1.com"
      }
    }
  }
]
}

Regenerating first key for a specific S3 user for the specified SVM

Note that if key_id is not specified, key with key_id=1 will be regenerated.

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X PATCH "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2?regenerate_keys=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ }"

# The response:
HTTP/1.1 200 OK
Date: Fri, 31 May 2019 09:55:45 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Length: 391
Content-Type: application/hal+json
{
"num_records": 1,
"records": [
  {
    "name": "user-2",
    "access_key": "KEOYV21G156K8AB4ZISH",
    "secret_key": "au__5oyYSs3c_QtoD5FH9f9rL888rwgD6fQS8chl",
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2"
      }
    }
  }
]
}

Regenerating second key for a specific S3 user for the specified SVM

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X PATCH "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2?regenerate_keys=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ \"key_id\":  \"2\" }"

# The response:
HTTP/1.1 200 OK
Date: Fri, 31 May 2019 09:55:45 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Length: 391
Content-Type: application/hal+json
{
"num_records": 1,
"records": [
  {
    "name": "user-2",
    "access_key": "FAKEACCESSKEYFAKEAC1",
    "secret_key": "<secret_key_here>",
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2"
      }
    }
  }
]
}

Regenerating keys and setting new expiry configuration for a specific S3 user for the specified SVM

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X PATCH "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2?regenerate_keys=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ \"key_time_to_live\": \"PT6H3M\" }"

# The response:
HTTP/1.1 200 OK
Date: Fri, 31 May 2019 09:55:45 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Length: 391
Content-Type: application/hal+json
{
"num_records": 1,
"records": [
  {
    "name": "user-2",
    "access_key": "FAKEACCESSKEYFAKEAC1",
    "secret_key": "<secret_key_here>",
    "key_expiry_time": "2023-06-16T16:19:06Z",
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2"
      }
    }
  }
]
}

Creating another key for a specific S3 user for the specified SVM using key_id '2'

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X PATCH "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2?regenerate_keys=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ \"key_time_to_live\": \"PT6H3M\", \"key_id\":  \"2\" }"

# The response:
HTTP/1.1 200 OK
Date: Fri, 31 May 2019 09:55:45 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Length: 391
Content-Type: application/hal+json
{
"num_records": 1,
"records": [
  {
    "name": "user-2",
    "access_key": "FAKEACCESSKEYFAKEAC1",
    "secret_key": "<secret_key_here>",
    "key_expiry_time": "2023-06-16T16:19:06Z",
    "_links": {
      "self": {
        "href": "/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2"
      }
    }
  }
]
}

Deleting first key for a specific S3 user for a specified SVM

Note that if key_id is not specified, key with key_id=1 will be deleted.

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X PATCH "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2?delete_keys=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ }"

# The response:
HTTP/1.1 200 OK
Date: Wed, 08 Feb 2023 13:40:04 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors: 'self'
Content-Length: 3
Content-Type: application/hal+json
Vary: Origin
{
}

Deleting second key for a specific S3 user for a specified SVM

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X PATCH "https://<mgmt-ip>/api/protocols/s3/services/db2ec036-8375-11e9-99e1-0050568e3ed9/users/user-2?delete_keys=true" -H "accept: application/hal+json" -H "Content-Type: application/json" -d "{ \"key_id\":  \"2\" }"

# The response:
HTTP/1.1 200 OK
Date: Wed, 08 Feb 2023 13:40:04 GMT
Server: libzapid-httpd
X-Content-Type-Options: nosniff
Cache-Control: no-cache,no-store,must-revalidate
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors: 'self'
Content-Length: 3
Content-Type: application/hal+json
Vary: Origin
{
}

Deleting the specified S3 user configuration for a specified SVM

# The API:
/api/protocols/s3/services/{svm.uuid}/users/{name}

# The call:
curl -X DELETE "https://<mgmt-ip>/api/protocols/s3/services/03ce5c36-f269-11e8-8852-0050568e5298/users/user-2" -H "accept: application/json"