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.
Warning
As soon as a client is deleted from the CipherTrust Data Security Platform Service, all communication between the CipherTrust Data Security Platform Service and the client will stop immediately. It is recommended that the clients are decrypted before deletion, otherwise the encrypted data will become inaccessible.
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:
client id | client name |
---|---|
17771cf2-f80b-4eb5-a19b-a2d0032179c3 | web-ui |
5ffb6fac-2cb5-4b91-8183-e20ad3b62577 | ksctl |
837c840d-75dd-4b4f-a318-79cb16ca248d | api-playground |
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:
Parameter | Description |
---|---|
Name | Name for the client to display on the CipherTrust Data Security Platform Service. |
Registration Token | Registration token to register the client with the CipherTrust Data Security Platform Service. |
High-Level Registration Flow for CTE and Custom Clients
-
Create a registration token. Retain this registration token.
-
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:
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.
-
Log on to the CipherTrust Data Security Platform Service GUI as administrator.
-
In the left pane, click Access Management > Registration Tokens.
-
On the right, click Add Registration Token. The Create New Registration Token wizard is displayed. This is a three-step wizard.
-
Click Begin to start token creation. The Configure Token screen is displayed.
-
(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 asks_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.
-
-
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. -
-
Specify Client Capacity. This is the maximum number of clients that can be registered using this registration token. The default capacity is
100
clients. -
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.
-
Select the desired encoding.
-
Click Copy next to the token. Save the copied token. This token will be used when registering and migrating clients.
-
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.