Security Microservices

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

The Security Microservices is divided into:

Authorization
Secure Storage

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 Microservices Conventions. These methods return a status code, as listed in the Microservices Status Codes.

Authorization

Use the CDAP Authorization Microservices to grant, revoke, and list privileges on CDAP entities. Details about authorization in CDAP can be found at 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 information 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 start with ns. ns? represents all namespaces that start with ns and followed 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.

Note: 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

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:

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

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

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:

Parameter	Description

Parameter	Description
`principal-type`	The principal type, one of `USER`, `GROUP`, or `ROLE`.
`principal-name`	Name of the principal.

HTTP Responses

Status Codes	Description

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):

Listing privileges are supported for USER, GROUP and ROLE type.

Secure Storage

Use the Secure Storage Microservices to create, retrieve, and delete secure keys.

Details about secure storage and secure keys in CDAP can be found in Secure Storage.

Create a Secure Key

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

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:

Parameter	Description

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. This could be a passphrase, cryptographic key, access token, service account JSON, or any other data that needs to be stored securely. Note: If you want to create a secure key for a Service Account in a Compute Profile for a Dataproc cluster, you must convert the service account JSON to a valid string, which means it must be converted into a single-line JSON string and all quotes need to be escaped.
`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

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:

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

Parameter	Description

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

HTTP Responses

Status Codes	Description

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:

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:

Parameter	Description

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

HTTP Responses

Status Codes	Description

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:

with the metadata of all of the secure keys 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:

Parameter	Description

Parameter	Description
`namespace-id`	Namespace ID.

HTTP Responses

Status Codes	Description

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:

Parameter	Description

Parameter	Description
`namespace-id`	Namespace ID.
`secure-key-id`	Name of the key to remove from secure storage.

HTTP Responses

Status Codes	Description

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.