Skip to main content

Security roles owner.uuid name privileges endpoint overview

Contributors

Overview

This API is used to configure the role privileges (tuples of REST URI paths or command/command directory paths, their access levels and optional queries, where the tuples refer to command/command directory paths). It also retrieves all of the privilege tuples for a role and can add a tuple to an existing role or creates a new role with the provided tuple. The "path" attribute can be a resource-qualified endpoint. Currently, the only supported resource-qualified endpoints are the following:

Snapshots APIs

/api/storage/volumes/{volume.uuid}/snapshots

File System Analytics APIs

/api/storage/volumes/{volume.uuid}/files

/api/storage/volumes/{volume.uuid}/top-metrics/clients

/api/storage/volumes/{volume.uuid}/top-metrics/directories

/api/storage/volumes/{volume.uuid}/top-metrics/files

/api/storage/volumes/{volume.uuid}/top-metrics/users

/api/svm/svms/{svm.uuid}/top-metrics/clients

/api/svm/svms/{svm.uuid}/top-metrics/directories

/api/svm/svms/{svm.uuid}/top-metrics/files

/api/svm/svms/{svm.uuid}/top-metrics/users

Ontap S3 APIs

/api/protocols/s3/services/{svm.uuid}/users

In the above APIs, wildcard character * could be used in place of {volume.uuid} or {svm.uuid} to denote all volumes or all SVMs, depending upon whether the REST endpoint references volumes or SVMs. The {volume.uuid} refers to the -instance-uuid field value in the "volume show" command output at diagnostic privilege level. It can also be fetched through REST endpoint /api/storage/volumes.

The role can be SVM-scoped or cluster-scoped.

Specify the owner UUID and the role name in the URI path. The owner UUID corresponds to the UUID of the SVM for which the role has been created and can be obtained from the response body of a GET request performed on one of the following APIs:

  • /api/security/roles for all the roles

  • /api/security/roles/?scope=svm for SVM-scoped roles

  • /api/security/roles/?owner.name=</i> for roles in a specific SVM This API response contains the complete URI for each role and can be used after suffixing it with _"privileges"._

Note The pre-defined roles can be retrieved but cannot be updated.

Examples

Adding a privilege tuple for a REST URI/endpoint to an existing custom role

# The API:
POST "/security/roles/{owner.uuid}/{name}/privileges"

# The call:
curl -X POST "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges" -d '{"access":"readonly","path":"/api/protocols"}'

Adding a privilege tuple for a command or command directory to an existing custom role

# The API:
POST "/security/roles/{owner.uuid}/{name}/privileges"

# The call:
curl -X POST "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges" -d '{"access":"all","path":"statistics volume show","query":"-vserver vs1&#124;vs2 -aggregate aggr1&#124;aggr2"}'

Retrieving all the privilege tuples for a REST role

# The API:
GET "/api/security/roles/{owner.uuid}/{name}/privileges"

# The call:
curl -X GET "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges"

# The response:
{
"records": [
  {
    "path": "/api/application",
    "access": "all",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fapplication"
      }
    }
  },
  {
    "path": "/api/protocols",
    "access": "readonly",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fprotocols"
      }
    }
  },
  {
    "path": "/api/storage/volumes/1385d680-74fc-4adb-a348-9a740e83702a/snapshots",
    "access": "all",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fstorage%2Fvolumes%2F1385d680-74fc-4adb-a348-9a740e83702a%2Fsnapshots"
      }
    }
  },
  {
    "path": "/api/storage/volumes/*/top-metrics/users",
    "access": "read_create_modify",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/%2Fapi%2Fstorage%2Fvolumes%2F%2A%2Ftop-metrics%2Fusers"
      }
    }
  }
],
"num_records": 4,
"_links": {
  "self": {
    "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges"
  }
}
}

Retrieving all the privilege tuples for a custom legacy role

# The API:
GET "/api/security/roles/{owner.uuid}/{name}/privileges"

# The call:
curl -X GET "https://<mgmt-ip>/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges"

# The response:
{
"records": [
  {
    "path": "network interface",
    "access": "readonly",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/network%20interface"
      }
    }
  },
  {
    "path": "security",
    "access": "readonly",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/security"
      }
    }
  },
  {
    "path": "security certificate"
    "access": "all",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/security%20certificate"
      }
    }
  },
  {
    "path": "security password"
    "access": "all",
    "_links": {
      "self": {
        "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges/security%20password"
      }
    }
  }
],
"num_records": 4,
"_links": {
  "self": {
    "href": "/api/security/roles/aaef7c38-4bd3-11e9-b238-0050568e2e25/svm_role1/privileges"
  }
}
}