Client Management

A client represents a machine where a supported product such as CipherTrust Transparent Encryption (CTE) is installed. It can also represent a generic client using the REST protocol.

All clients with supported product installations (for example, CTE) can be managed on the CipherTrust Data Security Platform Service. An Administrator can register many clients with the CipherTrust Data Security Platform Service, view registered clients, view and modify details, revoke registrations, and delete clients when they are no longer needed. We recommend to register a client whenever possible.

Client registration is supported with:

• CTE Agents

• Custom REST API clients

Registering a client with CipherTrust Data Security Platform Service allows you to better track client activity, through the assigned client identity.

The DPoD audit query records contain a client_id value whenever a registered or public client receives an authentication token.

CTE clients need to be registered with the CipherTrust Data Security Platform Service to successfully authenticate and perform key and cryptographic operations. When successfully registered, the client is automatically added to the CipherTrust Data Security Platform Service. CipherTrust Data Security Platform Service currently allows unregistered custom REST API clients.

A client can be registered with the CipherTrust Data Security Platform Service by using a registration token generated on the CipherTrust Data Security Platform Service. This token is called the client registration token. The CipherTrust Data Security Platform Service provides options to manage registration tokens and clients.

Public Clients

The CipherTrust Data Security Platform Service pre-registers the following public clients:

• ksctl

• Web-UI

• API playground

These public clients are shipped with the hard-coded client ids and names as follows:

The client ids are pre-embedded in the respective public clients. When public clients call the /v1/auth/tokens endpoint API to generate a registration token, it includes the client_id parameter with the password grant type. The client_id and client_name are present in the issued JWT after the successful authentication.

These client ids are included in DPoD audit query records.

Registering Clients

The following table lists the parameters that are required when managing a client on the CipherTrust Data Security Platform Service:

High-Level Registration Flow for CTE and Custom Clients

1. Create a registration token. Retain this registration token.

2. Have the client issue a client registration request to CipherTrust Data Security Platform Service including the registration token. The way you initiate this request is specific to the client type, but in all cases, you provide the registration token.

The client-side registration for specific client types is described at the following locations:

• Custom Rest API Client Registration

• Installing and Registering CTE

Tokens

A token is a string that is used to register clients with the CipherTrust Data Security Platform Service. The CipherTrust Data Security Platform Service provides options to create tokens, view existing tokens, view and modify their details, and delete them when they are no longer required.

Creating a Registration Token using GUI

A registration token can be created on the CipherTrust Data Security Platform Service. It is used when manually registering CipherTrust Data Security Platform Service clients with the CipherTrust Data Security Platform Service. A CipherTrust Data Security Platform Service administrator creates registration tokens.

1. Log on to the CipherTrust Data Security Platform Service GUI as administrator.

2. In the left pane, click Access Management > Registration Tokens.

3. On the right, click Add Registration Token. The Create New Registration Token wizard is displayed. This is a three-step wizard.

4. Click Begin to start token creation. The Configure Token screen is displayed.

5. (Optional) Specify a Name Prefix. Prefix for the client name. This prefix is used to construct names for clients whose names are not specified during registration with the CipherTrust Data Security Platform Service using this token.

   • If the name prefix is specified as ks_client, client names will be constructed as ks_client#; for example, ks_client1, ks_client2, ks_client3, and so on.

   • If the name prefix is not specified, the CipherTrust Data Security Platform Service will construct a random name for clients.

   However, if a client's name is specified during registration, this name prefix will not be used for that client.

6. Specify Token lifetime. This is the duration (in minutes, hours, or days) for which this token can be used for registering clients. For example, specify the lifetime as:

   • 1 minutes for 1 minute

   • 2 hours for 2 hours

   • 3 days for 3 days

   • unlimited for a token that never expires.

   By default, the token lifetime is unlimited. The token will never expire.

7. Specify Client Capacity. This is the maximum number of clients that can be registered using this registration token. The default capacity is 100 clients.

8. Click Create Token. The Create Token screen is displayed. The screen displays the generated registration token in ASCII and Base64 encoding. The CipherTrust Data Security Platform Service accepts the registration token in ASCII format only. Select Base64 if the client application accepts the token in Base64 format only and converts the token to ASCII before sending the it to the CipherTrust Data Security Platform Service.

9. Select the desired encoding.

10. Click Copy next to the token. Save the copied token. This token will be used when registering and migrating clients.

11. Click Add Token.

Managing Registration Token using ksctl

This section provides instructions to create and manage registration tokens on the CipherTrust Data Security Platform Service.

The following operations can be performed:

• Create/Get/Update/Delete/Update registration tokens

• List all client profiles

Creating Registration Token

To create a registration token, run

Syntax

ksctl clientmgmt tokens create --life-time <lifetime-of-token> --max-clients <maximum-number-of-client> --name-prefix <name-prefix>

• life-time - duration (in minutes, hours, or days) for which this token can be used for registering clients.

• max-clients - maximum number of clients that can be registered using this registration token.

• name-prefix - prefix for the client name. This prefix is used to construct names for clients whose names are not specified during registration with the CipherTrust Data Security Platform Service using this token. However, if a client's name is specified during registration, this name prefix will not be used for that client.

Getting Registration Token Details

To get details of a registration token, run:

Syntax

ksctl clientmgmt tokens get --token-id <token-id>

Example Request

ksctl clientmgmt tokens get --token-id "669457e6-89cc-482d-8cb5-3b35f2b1a89c"

Example Response

{
    "id": "669457e6-89cc-482d-8cb5-3b35f2b1a89c",
    "uri": "kylo:kylo:munshi:tokens:669457e6-89cc-482d-8cb5-3b35f2b1a89c",
    "account": "kylo:kylo:admin:accounts:kylo",
    "application": "ncryptify:gemalto:admin:apps:kylo",
    "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
    "createdAt": "2023-11-30T20:35:05.841579Z",
    "updatedAt": "2023-11-30T20:38:50.171348Z",
    "token": "4u9xQXsTknLcGT2byBrY4IJCOp40gWKIhEP7jxEUFJM27QDM1RgE26Fz43oSog1j",
    "valid_until": "2023-12-01T01:38:50.170988Z",
    "max_clients": 20,
    "cert_duration": 2,
    "clients_registered": 0,
    "ca_id": "",
    "name_prefix": "test_prefix",
    "label": null,
    "client_management_profile_id": "c5ce40bf-073c-49bb-977b-5933d6d36b71"
}

Updating Registration Tokens

To update a registration token, run:

Syntax

ksctl clientmgmt tokens update --token-id <token-id> --life-time <lifetime-of-token> --max-clients <maximum-number-of-client> --name-prefix <name-prefix>

Getting List of Registration Tokens

To list all registration tokens, run;

Syntax

Example Request

ksctl clientmgmt tokens list

Example Response

{
    "skip": 0,
    "limit": 10,
    "total": 1,
    "resources": [
        {
            "id": "ed307d73-695a-4c98-b1bd-a412d84b7b82",
            "uri": "kylo:kylo:munshi:tokens:ed307d73-695a-4c98-b1bd-a412d84b7b82",
            "account": "kylo:kylo:admin:accounts:kylo",
            "application": "ncryptify:gemalto:admin:apps:kylo",
            "devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
            "createdAt": "2023-11-29T11:19:41.044238Z",
            "updatedAt": "2023-11-29T11:39:13.306853Z",
            "token": "UD2lfsg4ZYJHGASOfWwJxPT6eqXFTLRgBBkDGxy5rrBcnGCs1uoM5MHluLZ65kW3",
            "valid_until": "0001-01-01T00:00:00Z",
            "max_clients": -1,
            "clients_registered": 5,
            "ca_id": "950f1ef4-7b47-4cbb-9bfb-adee2f2c0283",
            "label": null,
            "client_management_profile_id": "52d3041a-e958-4144-879e-eddbe6debc41"
        }
    ]
}

Deleting Registration Tokens

To delete a registration token, run:

Syntax

ksctl clientmgmt token delete --token-id <token-id>

Example Request

ksctl clientmgmt token delete --token-id "669457e6-89cc-482d-8cb5-3b35f2b1a89c"

Example Response

There will be no response if token is deleted successfully.