Client

Client credentials enable applications to authenticate as the Role assigned to the client record.

Commands that Act on Clients

Examples

Create

The create command accepts as its --role parameter a fully qualified Role name, and creates a client credential assigned to that Role.

dsv client create --role app-role

The output will include a clientId and clientSecret suitable for use during CLI installation, or within REST calls to authenticate as the Role assigned to the clientId.

{
  "clientId": "01234567-abcd-4eb9-9df4-6f1fea7d9298",
  "clientSecret": "aaabbb777DwTLkdzWkL18UF9blycz3r9yfRhQTYICFc",
  "created": "2022-09-16T09:53:50Z",
  "createdBy": "users:bright",
  "id": "00000000-0123-0123-0123-0123456789ab",
  "role": "app-role",
  "url": false
}

NOTE: The client Secret is available only when you create the client. If the Secret is lost, delete the client and create a new one.

Ephemeral Credentials

Client credentials can be made temporary by using the --uses and --ttl flags.

--uses determines the number of times the client credential can be read. If set to 0, it can be used infinitely. Uses defaults to 0.

--ttl determines long until the client credential expires. If set to 0, it can be used indefinitely. Ttl defaults to 0.

Search

The search command accepts as its --query parameter the name of a Role, and searches for clients having that Role.

dsv client search --query dev-role

or

dsv client search dev-role

Read

The read command accepts a client ID as a parameter and returns the details for the given client. As with most commands, remember that you can apply flags to beautify, redirect, or reformat the returned material.

dsv client read --client-id 01234567-abcd-4eb9-9df4-6f1fea7d9298

Delete

The delete command accepts a client ID as a parameter and deletes from the vault the indicated client.

dsv client delete --client-id 01234567-abcd-4eb9-9df4-6f1fea7d9298

When you delete a Client, it will no longer be usable. However, with the soft delete capacity of VP-DV, you have 72 hours to use the restore command to undelete the Client. After 72 hours, the Client will no longer be retrievable.

Should you want to perform a hard delete, precluding any restore operation, you can use the delete command’s --force flag.

Bootstrapping

There will be times when machines or applications will require access to VP-DV to get started, but you can't (or don't want) to hardcode the client secret. In this case, we can create the client ID and get a one-time use URL. When the URL is accessed, then the corresponding client secret will be created and returned. The URL will no longer be valid after the initial use, so if the intended machine or application gets an error "url already used" then there should be an alarm to investigate.

First create the Client ID and URL:

dsv client create --role <role> --url --url-ttl <ttl in seconds>

Where "role" is a Role created earlier and is attached to a Policy to provide the proper permissions.

--url if present tells VP-DV to create a one-time use URL instead of a Client Secret right now.

--url-ttl is the time to live of the URL in seconds. If it is not accessed in that time frame, then the URL will become invalid.

If a TTL is set for both the URL and the underlying client credentials, then the timer for the client credentials will not start until the URL is accessed.

The result will look something like this:

{
  "clientId": "01234567-abcd-4eb9-9df4-6f1fea7d9298",
  "created": "2022-09-16T11:04:45Z",
  "createdBy": "users:admin@company.com",
  "id": "c6bae4ae-469f-4ea7-a72a-8f338fee4867",
  "role": "app-role",
  "url": true,
  "urlExpires": "2022-09-16T12:04:45Z",
  "urlPath": "https://company.secrestvaultcloud.com/v1/clients/bootstrap/01234567-abcd-4eb9-9df4-6f1fea7d9298",
  "urlTTL": 3600
}

Then the machine or application can access that urlpath for the Client Secret. For Example, using CURL (or Invoke-RestMethod for Powershell):

curl https://company.secrestvaultcloud.com/v1/clients/bootstrap/01234567-abcd-4eb9-9df4-6f1fea7d9298

With a result containing the Client Secret:

{
  "id": "c6bae4ae-469f-4ea7-a72a-8f338fee4867",
  "clientId": "01234567-abcd-4eb9-9df4-6f1fea7d9298",
  "clientSecret": "abcdef0123456789ALGewTlxf4Fdo-cTkS_l_o0ki8w",
  "role": "app-role",
  "url": true,
  "urlExpires": "2022-09-16T12:04:45Z",
  "accessed": "2022-09-16T11:08:11Z",
  "created": "2022-09-16T11:04:45Z",
  "createdBy": "users:admin@company.com"
}

If the URL is accessed a second time, then the response will contain: {"code":400,"message":"url has already been used"}