Security HTTP RESTful API

Use the Security HTTP RESTful API to manage privileges (authorization) of users on CDAP entities as well as manage secure storage.

The HTTP RESTful API is divided into:

All methods or endpoints described in this API have a base URL (typically http://<host>:11015 or https://<host>:10443) that precedes the resource identifier, as described in the RESTful API Conventions. These methods return a status code, as listed in the RESTful API Status Codes.

Authorization

Use the CDAP Authorization HTTP RESTful API to grant, revoke, and list privileges on CDAP entities. Details about authorization in CDAP can be found at Admin' Manual: Authorization.

In this API, a JSON-formatted body is used that contains the principal, the CDAP authorizable, and the privileges to be granted:

{
  "authorizable": {
    "entityType": "DATASET",
    "entityParts": {"NAMESPACE": "default", "DATASET": "dataset"}
  },
  "principal": {
    "name": "admin",
    "type": "ROLE"
  },
  "actions": ["READ", "WRITE", "ADMIN"]
}

In the above JSON body, the authorizable object is the JSON-serialized form of the CDAP Authorizable class.—for example, for datasets, its entity type is DATASET and it can be constructed by the namespace and dataset name. More info can be found at the DatasetId class. In entity parts, the name of the entity can be represented using wildcard by including * and ? in the name. For example, ns* represents all namespaces that starts with ns. ns? represents all namespaces that starts with ns and follows by a single character.

The principal object refers to the principal that you want to grant the privileges to. Principals have a name and a type. The supported types are USER, GROUP and ROLE.

Please note that the REST endpoints have only been created for supporting Apache Sentry.

The actions list contains the actions you want to grant the principal on the entity. The supported actions are READ, WRITE, ADMIN, and EXECUTE.

Grant Privileges

You can grant privileges to a principal on a CDAP Entity by making an HTTP POST request to the URL:

POST /v3/security/authorization/privileges/grant

with JSON-formatted body that contains the principal, the CDAP entity, and the actions to be granted, such as:

{
  "authorizable": {
    "entityType": "DATASET",
    "entityParts": {"NAMESPACE": "default", "DATASET": "dataset"}
  },
  "principal": {
    "name": "admin",
    "type": "ROLE"
  },
  "actions": ["READ", "WRITE", "ADMIN"]
}
  • Granting privileges is only supported for ROLE type.

HTTP Responses

Status Codes Description
200 OK Privileges were successfully granted for the specified principal

Revoke Privileges

You can revoke privileges for a principal on a CDAP Entity by making an HTTP POST request to the URL:

POST /v3/security/authorization/privileges/revoke

with JSON-formatted body that contains the principal, the CDAP entity and the actions to be revoked:

{
  "authorizable": {
    "entityType": "DATASET",
    "entityParts": {"NAMESPACE": "default", "DATASET": "dataset"}
  },
  "principal": {
    "name": "admin",
    "type": "ROLE"
  },
  "actions": ["READ", "WRITE", "ADMIN"]
}

The authorizable object is mandatory in a revoke request.

  • If both principal and actions are not provided, then the API revokes all privileges on the specified entity for all principals.
  • If authorizable and principal are provided, but actions is not, the API revokes all actions (READ, WRITE, ADMIN, and EXECUTE) on the specified entity for the specified principal.
  • Revoking privileges is only supported for ROLE type.

HTTP Responses

Status Codes Description
200 OK Privileges were successfully revoked

List Privileges

You can list all privileges for a principal on all CDAP entities by making an HTTP GET request to the URL:

GET /v3/security/authorization/<principal-type>/<principal-name>/privileges
Parameter Description
principal-type The principal type, one of USER, GROUP, or ROLE
principal-name Name of the principal

HTTP Responses

Status Codes Description
200 OK Privileges were successfully listed for the specified principal

This will return a JSON array that lists each privilege for the principal with its authorizable and action. Example output (pretty-printed):

[
  {
    "authorizable": {
      "entityType": "DATASET",
      "entityParts": {"NAMESPACE": "default", "DATASET": "dataset"}
    },
    "action": "WRITE"
  },
  {
    "authorizable": {
      "entityType": "NAMESPACE",
      "entityParts": {"NAMESPACE": "default"}
    },
    "action": "READ"
  },
  {
    "authorizable": {
      "entityType": "PROGRAM",
      "entityParts":{"NAMESPACE": "default", "APPLICATION": "HelloWorld", "PROGRAM": "flow.testFlow"}
    },
    "action": "EXECUTE"
  }
]
  • Listing privileges are supported for USER, GROUP and ROLE type.

Secure Storage

Use the Secure Storage HTTP RESTful API to create, retrieve, and delete secure keys. Details about secure storage and secure keys in CDAP can be found in Administration Manual: Secure Storage.

Note: In CDAP 3.5.0, encryption and decryption of the contents only happens at the secure store, not while the data is transitting to the secure store. In a later version of CDAP, all transport involving secure keys will be secured using SSL.

Add a Secure Key

You can add a secure key to secure storage by making an HTTP PUT request to the URL:

PUT /v3/namespaces/<namespace-id>/securekeys/<secure-key-id>

with a JSON-formatted body that contains the description of the key, the data to be stored under the key, and a map of properties associated with the key:

{
  "description": "Example Secure Key",
  "data": "<secure-contents>",
  "properties": {
    "<property-key>": "<property-value>"
  }
}
Parameter Description
namespace-id Namespace ID
secure-key-id Name of the key to add to secure storage
secure-contents String data to be added under the key
property-key Name of a property key to associate with the secure key
property-value Value associated with the property key

HTTP Responses

Status Codes Description
200 OK The secure key was successfully added to secure storage
400 BAD REQUEST An incorrectly-formatted body was sent with the request or the data field in the request was empty or not present
404 NOT FOUND The namespace specified in the request does not exist

Retrieve a Secure Key

You can retrieve a secure key from secure storage by making an HTTP GET request to the URL:

GET /v3/namespaces/<namespace-id>/securekeys/<secure-key-id>

with the data of the secure key returned as text, passed in the response body.

Parameter Description
namespace-id Namespace ID
secure-key-id Name of the key to retrieve from secure storage

HTTP Responses

Status Codes Description
200 OK The secure key was successfully retrieved
404 NOT FOUND The namespace specified in the request does not exist or the secure key with that name does not exist in that namespace

Retrieve the Metadata for a Secure Key

You can retrieve just the metadata for a secure key from secure storage by making an HTTP GET request to the URL:

GET /v3/namespaces/<namespace-id>/securekeys/<secure-key-id>/metadata

with the metadata of the secure key returned as a JSON object—name (the secure-key-id), description, created timestamp, and the map of properties—passed in the response body, shown here pretty-printed:

{
  "name": "<secure-key-id>",
  "description": "Example Secure Key",
  "createdEpochMs": 1471718010326,
  "properties": {
    "property-key": "property-value"
  }
}
Parameter Description
namespace-id Namespace ID
secure-key-id Name of the key to retrieve from secure storage

HTTP Responses

Status Codes Description
200 OK Metadata for the secure key was successfully retrieved
404 NOT FOUND The namespace specified in the request does not exist or a secure key by the specified name does not exist in the specified namespace

List all Secure Keys

You can retrieve all the keys in a namespace from secure storage by making an HTTP GET request to the URL:

GET /v3/namespaces/<namespace-id>/securekeys

with the secure keys in the namespace returned as a JSON string map of string-string pairs, passed in the response body (shown here pretty-printed):

{
  secure-key-id-1: data-1,
  secure-key-id-2: data-2,
  ...
}

such as (depending on what was stored):

{
  "securekey": "securedata",
  "password": "passw0rd",
  ...
}
Parameter Description
namespace-id Namespace ID

HTTP Responses

Status Codes Description
200 OK The keys were successfully retrieved
404 NOT FOUND The namespace specified in the request does not exist

Remove a Secure Key

You can remove a secure key from secure storage by making an HTTP DELETE request to the URL:

DELETE /v3/namespaces/<namespace-id>/securekeys/<secure-key-id>
Parameter Description
namespace-id Namespace ID
secure-key-id Name of the key to remove from secure storage

HTTP Responses

Status Codes Description
200 OK The key was successfully removed
404 NOT FOUND The namespace specified in the request does not exist or a secure key by the specified name does not exist in the specified namespace