This feature is in Beta.

Implementing column-level access control is a mix of UI and API tasks. 



This topic includes:

1 Select a Table

Identify a table to which you want to add column-level access control.

2 Create a Column Identity Type

Create a customized column identifier using the POST/v1/annotation-type API. Some examples of column identifiers are personal identity information (PII), finance, sensitive, and so on.

POST /v1/annotation-type

Create a customized annotation type. Only administrators can call this API.

Method

Resource

Description

POST

/v1/annotation-type

Create an annotation type.

Request Body

Property Name

Value

Description

attributes

object

Parameters:

attributes.comment: A description of the annotation type.

attributes.humanReadableName: The name of the annotation type that displays in the UI.

attributes.name: The name of the annotation used in the Permission Policy API.

Sample Request

curl  -H "Authorization: TD1 ${TD1_KEY}" 
      -H "Content-Type: application/json" \ 
      -d '{"data":{"attributes":{"name":"PII","humanReadableName":"PII"}}}' \

Sample Response

{
 - "attributes":{
         "name":"PII",
         "humanReadableName":"PII",
         "comment":null,
         "version":1,
         "createdAt":"2021-06-01T20:47:59.245153Z",
         "updatedAt":"2021-06-01T20:47:59.245153Z"
   },
   "id":"6bfd1842-503e-4f31-a88c-678f9bf07207",
   "type":"annotation-type"
}

3 Verify New Column Type

Verify the new column identified using the GET /v1/annotation-type/custom API.

GET /v1/annotation-type/custom

Request a list of annotation types provided by default to all accounts.

Method

Resource

Description

GET

v1/annotation-type/custom


Get a list of custom annotation types.

URI Parameters

Parameter Name

Required

Type

Description

tableID

No

String

Database Name and Table Name

Format: DatabaseId.TableId

Example:1234.5678

keyset

No

String

Unique ID for the next page

Example: 2020-07-13T16:49:08.171013Z|ffbc617e-1235-4a7d-9168-033c75dc6601

Sample Response

The following response returns a JSON array with one item calling out the relationship between one annotation and one column. In this example, the annotation is email-raw and the column is agent. If there’s another column with another annotation, that will be another JSON item within the same “data” JSON array. For example, there can be another column that’s tagged with email-raw or the column “agent” is tagged with another annotation.


Status: 200 Success

{
  "data": [
    {
      "type": "column-annotation",
      "id": "60d57893-d96a-456f-a6c8-e286ff9465e7",
      "attributes": {
        "comment": "",
        "createdAt": "2021-04-14T19:37:21.994770Z",
        "payload": {
          "sensitive": false
        }
      },
      "relationships": {
        "annotation-type": {
          "data": {
            "type": "annotation-type",
            "id": "ecd4f9e2-a11f-11ea-b759-acde48001122",
            "name": "email-raw"
          }
        },
        "table": {
          "data": {
            "type": "treasure-data-table",
            "id": "484834.2767455"
          }
        },
        "column": {
          "data": {
            "type": "treasure-data-column",
            "id": "agent"
          }
        },
        "created-by": {
          "data": {
            "type": "treasure-data-user",
            "id": "18174"
          }
        }
      }
    }
  ],
  "links": {
    "first": "/v1/column-annotation?filter%5BtableId%5D=484834.2767455",
    "self": "/v1/column-annotation?filter%5BtableId%5D=484834.2767455"
  },
  "meta": {
    "perPage": 250
  }
}

4 Apply Identity Type to Column

POST/v1/columns-annotation/bulk

Apply a custom tag to a column for column-level access.

Method

Resource

Description

POST

v1/column-annotation/bulk

Apply a custom tag to a column.

URI Parameters

Parameter Name

Required

Type

Description

tableID

Yes

String

Database Name and Table Name

Format: DatabaseId.TableId

Example:1234.5678

Request Body

Property Name

Value

Description

type

string

treasure-data-column

attributes

object

Parameters:

attributes.comment: A description of the relationship between the annotation and the table

attributes.sensitive: If true, indicates that the column contains sensitive data

relationship

object

Parameters:

Name of relationship

relationships.annotation-type: The annotation to attach to the column

relationships.column: The column to be annotated

Sample Request


{ 
    "data": [ 
       { 
          "type": "string", 
          "attributes": { 
          "comment": "string", 
          "sensitive": true 
         }, 
         "relationships": { 
            "annotation-type": { 
                "data": { 
                   "id": "00000000-0000-0000-0000-000000000000", 
                   "type": "annotation-type" 
               } 
            }, 
            "column": { 
               "data": { 
                  "id": "column", 
                  "type": "treasure-data-column"
                } 
            } 
        } 
     } 
  ] 
}

Sample Response - Status: 201 Success

{ 
    "data": [ 
        {
            "type": "column-annotation", 
            "id": "00000000-0000-0000-0000-000000000000", 
             "attributes": { 
                "comment": "string", 
                "createdAt": "2020-07-09T19:08:01Z", 
                "sensitive": true
           }, 
           "relationships": { 
              "annotation-type": { 
                 "data": {
                     "id": "00000000-0000-0000-0000-000000000000", 
                     "type": "annotation-type" 
                 } 
              }, 
              "table": { 
                "data": { 
                   "id": "1234.5678", 
                   "type": "treasure-data-table" 
                } 
              }, 
              "column": { 
                 "data": { 
                    "id": "column", 
                    "type": "treasure-data-column"
                 } 
              }, 
              "created-by": { 
                 "data": { 
                 "id": "user", 
                 "type": "treasure-data-user" 
                 } 
              } 
          } 
      } 
   ],
    "links": { 
       "first": "/v1/foo", 
       "self": "/v1/foo", 
       "next": "/v1/foo?page[keyset]=abc123" 
     }, 
     "meta": { 
         "perPage": 250
     } 
}

5 Create a Policy and Apply it to Yourself

  1. Open TD Console.

  2. Navigate to Control Panel > Policies.

  3. Select Actions > Create Policy.

6 Set Up For Policy Testing

In the policy you just created, don't forget to remove your name from "Columns full" for testing purposes.

7 Prepare Master API Key

Use the TD Toolbelt to retrieve the Master API key from the command line.

$ td apikey:show

8 Configure Policy Column Permissions

PATCH /v3/access_control/policies/:policy_id/column_permissions

This operation updates information related to a column-level access control policy. 

Control Type

Description

Allow

A policy that allows access with “xxx, yyy, zzz” tags

Allow - Except

A policy that allows access to all columns with the exception of “aaa, bbb, ccc” tags

Mask

A policy that hides specified columns using modified content.

ALLOW

HTTP Verb

Resource

Description

PATCH

/v3/access_control/policies/:policy_id/column_permissions

Updates a specific policy to allow access to specific tags.

URI Parameters

Parameter Name

Required

Type

Description

policy_id

Yes

integer

policy_id

Example: 6196842

Sample Request

curl -X PATCH 
     -H "Authorization: TD1 ${TD1_KEY}" 
     -H "Content-Type: application/json" \
     -d '{"column_permissions":[ {"tags":["home-address"]} ]}' 

Sample Response

[
  {
    "tags": [
      "home-address"
    ]
  }
]

ALLOW Except

HTTP Verb

Resource

Description

PATCH

/v3/access_control/policies/:policy_id/column_permissions

Updates a specific policy to allow access to specific tags.

URI Parameters

Parameter Name

Required

Type

Description

policy_id

Yes

integer

policy_id

Example: 6196842

Sample Request

curl -X PATCH 
     -H "Authorization: TD1 ${TD1_KEY}" 
     -H "Content-Type: application/json" \
     -d '{"column_permissions":[ {"tags":["email-raw"], "except":true} ]}' 

Sample Response

[
  {
    "tags": [
      "email-raw"
    ],
    “except”: true
  }
]

MASKING

HTTP Verb

Resource

Description

PATCH

/v3/access_control/policies/:policy_id/column_permissions

Updates a specific policy to allow access to specific tags.

URI Parameters

Parameter Name

Required

Type

Description

policy_id

Yes

integer

policy_id

Example: 6196842

Sample Request

curl -X PATCH 
     -H "Authorization: TD1 ${TD1_KEY}" 
     -H "Content-Type: application/json" \
     -d '{"column_permissions":[ {"tags":["home-address"], "masking":"hash"} ]}' 

Sample Response

[
  {
    "tags": [
      "home-address”
    ],
    “masking”: “hash”
  }
]

9 Run Queries

Review Client Library REST APIs for information on how to run queries.

10 Debug

Review Premium Audit Log Events.


  • No labels