Interfaces

This section provides an overview of the CipherTrust Manager interfaces that can be used for CDP related operations.

Authenticating to the Embedded API Guide

The embedded API Guide shares authentication with the CipherTrust Web UI. To authenticate to both the API Guide and the CipherTrust Web UI, visit https://<ciphertrust_manager_IP_or_hostname> in a web browser. Alternatively, click the Log In link in the top right corner of the API Guide when you are unauthenticated.

The simplest login is with a username and password. This authenticates a local user to the root domain. There can be additional login options to authenticate to another domain, authenticate with a certificate, authenticate using LDAP, or authenticate using OIDC. These options require additional user management configuration from a user in the User Admins group.

After login, the API Guide is accessible through the API button in the upper right corner.

There, you can make API calls in the established authentication context. You are logged out after 10 minutes of inactivity with the API Guide open. If you close the browser window, you are logged out after 30 minutes of your last login.

Manual API Token Generation for User Credentials

You can generate an API token with a user's username and password for a given domain, outside of the embedded API guide. This is useful if you have created a custom REST API client.

To copy and paste the following example commands, set an environment variable to point to your CipherTrust Manager instance:

$ export KSCTL_URL=https://{addr}               # sh/bash
$ set -x KSCTL_URL=https://{addr}               # fish

For example, this command will use the root admin's credentials to create an API token:

$ curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"admin\",\"password\":\"admin\"}"

Note

By default, this command creates a token for the root domain. You can specify a child domain to log in to with "{\"name\":\"domain_user\",\"password\":\"domain_user_password\", \"domain\":\"domain_name\"}"

The response:

{
  "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4",
  "duration":300
}

Copy the value of the jwt property into another environment variable:

(sh)  $ export KSCTL_JWT=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4
(fish)$ set -x KSCTL_JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4

Using the jq tool, we can fetch, extract, and export the token in a single shell command:

(sh)  $ export KSCTL_JWT=$(curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
                                    -H "Content-Type: application/json" \
                                    -d "{\"name\":\"admin\",\"password\":\"admin\"}" | jq -r '.jwt')
(fish)$ set -x KSCTL_JWT (curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
                                   -H "Content-Type: application/json" \
                                   -d "{\"name\":\"admin\",\"password\":\"admin\"}" | jq -r '.jwt')

We can use that API token to make other calls:

$ curl -k "$KSCTL_URL/api/v1/vault/keys2?limit=20" \
     -H "Authorization: Bearer $KSCTL_JWT"

Making an API Call

To make an API call, find the API in the left pane and click it. In the right pane, specify the required parameters, and click an appropriate button (for example, POST, GET, DELETE, or Curl). For example, to list the databases added for migration on CipherTrust Manager:

1. In the left pane of the API playground, click CDP.

2. Under Database/v1/protectdb/databases, click Add.

3. In the body field, specify required parameters with their values, as shown below.

   {
       "database_type" :"Oracle",
       "name" :"alias2",
       "host":"10.1.1.1",
       "database_port":"1521",
       "connection_Protocol" :"tcp",
       "database_user" :"test",
       "database_password" :"asdftest",
       "metadb_user":"ingrian",
       "meta_password" : "asdftest",
       "database_name":"orcl"
   }

   Copy

   Expand schema under the body field for names and types of fields. Hover your mouse over each field to view its description. The parameter names and casing in the body field must match with those shown in the schema. Also, ensure that parameters and their values are specified in double quotes.

4. Click POST.

Alternatively, to get an equivalent curl command, click the Curl button. The curl equivalent will be shown in the text field below. Use the curl tool to run the command to make the REST API call.

Similarly, all API calls can be made by referring to the schema shown in the playground.

GUI

Use the CipherTrust Manager's GUI to perform CDP management functions, such as database connection, user mapping, add table, and encryption configuration. These functions can also be performed using the REST APIs.

To use the GUI:

1. Open the CipherTrust Manager URL in a browser.

2. Enter Username and Password.

3. Click Log In. By default, the Products page is displayed.

4. Click Database Protection to open the application. The Databases page is displayed on the right.

Use the Databases page to view details of existing database connections or set up new connections, view/add/delete/modify database tables, user mappings, and configure/modify column level encryption properties.