Configure Secrets Management

The CipherTrust Manager version 2.17 onward, the CipherTrust Secrets Management (CSM) functionality is disabled by default. Disabling a product stops all its supporting services. When you upgrade from older CipherTrust Manager instances, the default functionality remains the same as defined for the older instance.

The CipherTrust Manager provides an interface to the administrator to enable/disable CSM.

Prerequisites

• Install the ksctl CLI on a remote workstation to issue these commands.

• CipherTrust Manager is up and running. Refer to CipherTrust Manager Deployment for details.

• Ensure that there is public network connectivity to Akeyless SaaS Core Services.

Enable CipherTrust Secrets Management

ksctl products enable --name <product-name>

ksctl products enable --name csm

{
    "state": "enabled"
}

ksctl products enable --name ""

{
        "code": 15,
        "codeDesc": "NCERRBadRequest: Bad HTTP request",
        "message": "product name can't be empty"
}

Note

After enabling the CSM, the supporting services take some time to start and run.

Disable CipherTrust Secrets Management

ksctl products disable --name <product-name>

ksctl products disable --name csm

{
    "state": "disabled"
}

ksctl products disable --name ""

{
        "code": 15,
        "codeDesc": "NCERRBadRequest: Bad HTTP request",
        "message": "product name can't be empty"
}

Note

After disabling the CSM, the supporting services take some time to stop and go offline.

Get State of CipherTrust Secrets Management

To fetch the state of CSM:

Syntax

ksctl products get-state --name <product-name>

Example Request 1 (valid product name)

ksctl products get-state --name csm

Example Response 1

{
        "state": "enabled"
}

Example Request 2 (empty product name)

ksctl products get-state --name ""

Example Response 2

{
        "code": 15,
        "codeDesc": "NCERRBadRequest: Bad HTTP request",
        "message": "product name can't be empty"
}

The incorrect product name or empty request throws an error message.

Get Details of CipherTrust Secrets Management

To get details of CSM:

Syntax

ksctl products list --name <product-name/ID>

Example Request 1 (valid product name)

ksctl products list --name csm

Example Response 1

{
        "skip": 0,
        "limit": 10,
        "total": 1,
        "resources": [
                {
                        "id": "8bdd3e1d-b8df-4cb4-92d2-5cd4acc5841d",
                        "uri": "kylo:kylo:solo:Product:8bdd3e1d-b8df-4cb4-92d2-5cd4acc5841d",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2024-05-06T16:29:34.184812Z",
                        "name": "csm",
                        "state": "enabled",
                        "description": "CipherTrust Secret Management",
                        "updatedAt": "2024-05-07T06:06:08.938346Z"
                }
        ]
}

Example Request 2 (invalid product name)

ksctl products list --name 'invalidname'

Example Response 2

{
        "skip": 0,
        "limit": 10,
        "total": 0,
        "resources": []
}

Example Request 3 (complete list)

ksctl products list

Example Response 3

{
        "skip": 0,
        "limit": 10,
        "total": 1,
        "resources": [
                {
                        "id": "8bdd3e1d-b8df-4cb4-92d2-5cd4acc5841d",
                        "uri": "kylo:kylo:solo:Product:8bdd3e1d-b8df-4cb4-92d2-5cd4acc5841d",
                        "account": "kylo:kylo:admin:accounts:kylo",
                        "createdAt": "2024-05-06T16:29:34.184812Z",
                        "name": "csm",
                        "state": "enabled",
                        "description": "CipherTrust Secret Management",
                        "updatedAt": "2024-05-07T06:06:08.938346Z"
                }
        ]
}

The following section describes the configuration needed to set up the Akeyless gateway before you can manage secrets.

Configure Akeyless Gateway

Automated Configuration

Note

CipherTrust Manager 2.19 onward, the configuration of Akeyless gateway is automated.

1. Create an Akeyless account with administrative privileges.

2. After the Akeyless account is created, it automatically creates:

   • Auth method named default-jwk-json-auth-method

   • Access role named default-jwk-role

   • dfc-key named default-dfc-key

   Consequently, the Akeyless config gets updated with the "sso-access-id" present in "default-jwk-json-auth-method".

   Wait for a few minutes for the Akeyless gateway to be up. This enables the Secrets Management tile on the CipherTrust Manager.

3. Manage customer fragments.

   Initially, CipherTrust Manager generates a customer fragment by default that could be used to create protection keys on the Akeyless gateway. Apart from this default customer fragment, you can also create a new customer fragment. Refer to Managing Multiple Customer Fragments in CipherTrust Manager for details.

   

   Caution

   Creating or deleting a customer fragment triggers the Akeyless gateway restart across all the nodes of a cluster.

4. You can configure the Akeyless gateway for using a CipherTrust Manager generated customer fragment to protect the Akeyless secrets. See Configure Akeyless Gateway for Using CM Customer Fragment.

Manual Configuration

1. Create an Akeyless account with administrative privileges.

2. In the CipherTrust Manager application, as an application administrator such as admin, rotate the authentication key to an ECDSA key.

3. Sign in to Akeyless account using the Access ID and Access Key obtained from step 1.

4. Navigate to Users & Auth Methods > New > Oauth2.0/JWT.

   

   Note

   It is recommended to delete the User-Admin role, as it is not required. The new Oauth 2.0/JWT method controls Akeyless permissions for CipherTrust Manager users.

5. Provide a name for the authentication method. Example, test-am.

6. (Optional) Change the default value of the JWT TTL (in minutes) field as required. It controls the expiry time for the Akeyless token issued for CipherTrust Manager users.

7. Click Next.

8. Configure the authentication method either using JSON or the Gateway option.

   JSON

   1. Select the JSON tab.

      

   2. Enter the Public key JWKS in the JWKs JSON field. See GET Public key JWKS to learn how to get public key JWKS.

   Example

   {
       "keys": [
           {
           "crv": "P-256",
           "kty": "EC",
           "x": "b5y6sdqZpB5HcciwP_Fl0K4s3czQFG6tZwmXLAJxGH4",
           "y": "OKrI2Gg0xkBN1hJTO1Ai7uRBmXiYbm18qgWJHw1zW-c"
           }
       ]
   }

   Copy
   1. Enter the value for Unique Identifier. For example, "sub".
   Gateway

   

   Note

   Ensure that the CN of the web interface server certificate is added in the DNS Hosts with the IP address of 172.30.0.203 in the CipherTrust Manager application. See Configuring DNS Hosts.

   1. Select the Gateway tab.

      

   2. From the Gateway drop-down, select defaultCluster or any other gateway configured for connecting to CipherTrust Manager application.

   3. Enter the URL in the JWKs URL field.

      The URL depends on the web interface certificate configuration performed in CipherTrust Manager.

      • If web server certificate is changed, use https://CN:8443/v1/auth/jwks.json as URL, where CN is the CN of the server certificate.
      • If no changes were done in web server certificate, use the default URL https://web.ciphertrustmanager.local:8443/v1/auth/jwks.json.

   4. (Optional) Upload the CA certificate in the Certificate field.

      

      Note

      The CA authority that signed the web interface server certificate must be trusted by Akeyless gateway. By default, the default root CA of CipherTrust Manager is trusted by Akeyless gateway.

      If your web interface server certificate is self signed or signed by an external CA, then you need to upload the certificate to the akeyless gateway.

      For more details, see Akeyless Online Documentation.

   5. Enter the value for Unique Identifier.

9. Click Finish.

10. Note the Access ID of the authentication method. This will be required to configure Akeyless connection in CipherTrust Manager.

11. Associate the authentication method created above to an existing access role or create a new access role. See Akeyless Access Role.

    

    Note

    You must associate the new authentication method to at least one Access Role, to determine the Akeyless console permissions of CipherTrust Manager users. These steps set up permissions for all CipherTrust Manager users to manage secrets. You can adjust settings on both CipherTrust Manager GUI and Akeyless console to restrict secrets management to fewer CipherTrust Manager users, if desired.

    See Akeyless Online Documentation for more information on Akeyless Access Roles.

12. In CipherTrust Manager application, set SSO Access ID to access ID of Oauth 2.0/JWT authentication method created above. See Set SSO Access ID.

    Initially, CipherTrust Manager generates a customer fragment by default that could be used to create protection keys on the Akeyless gateway. Apart from this default customer fragment, you can also create new customer fragment. Refer to Managing Multiple Customer Fragments in CipherTrust Manager for details.

    

    Caution

    Creating or deleting a customer fragment triggers an Akeyless gateway restart across all the nodes of a cluster.

13. Manage customer fragments.

    Initially, CipherTrust Manager generates a customer fragment by default that could be used to create protection keys on the Akeyless gateway. Apart from this default customer fragment, you can also create new customer fragment. Refer to Managing Multiple Customer Fragments in CipherTrust Manager for details.

    

    Caution

    Creating or deleting a customer fragment triggers an Akeyless gateway restart across all the nodes of a cluster.

14. Restart the CipherTrust Manager services.

    1. Navigate to Admin Settings > Services.

    2. Click System Restart to restart all services and apply the Akeyless configuration changes.

15. Once CipherTrust Manager GUI is available again, log in as any user. Ensure that the Secrets Management tile is enabled.

    If you click the tile, single sign-on takes place silently. The CipherTrust Manager issues a token for Akeyless to verify with the ECDSA signing key and you are logged into the Akeyless console.

16. You can configure the Akeyless gateway for using the CipherTrust Manager generated customer fragment to protect Akeyless secrets. See Configure Akeyless Gateway for Using CM Customer Fragment.

Create Akeyless account

This procedure provides you with a 90 day free trial to Akeyless Vault Platform, with settings that are suitable for CipherTrust Manager integration.

1. Navigate to https://<ciphertrust_manager_hostname>/akeyless-console/.

   The Akeyless Vault Platform interface is displayed.

2. Sign up using your email ID. You will receive a confirmation email to activate your account.

3. Open the confirmation email and click Activate your account.

   The account credentials are displayed in a browser window.

4. Note down the Access ID and Access Key. These are the Super-Admin credentials. You can also save these credentials to a CSV file. These credentials will be used for future sign in.

Note

• After a successful sign up, a new connection is created in the Connection Manager prefixed autogenerated-akeyless-connection.

• The connection ID is updated in the Akeyless configs API as the gateway_connection_id.

• This connection is created using the Gateway-Admin credentials. These credentials are fetched in the background while the user signs up and are used to create a connection.

Rotate Authentication Key

To rotate the CipherTrust Manager authentication key to an ECDSA key, run the following command as CipherTrust Manager Application Administrator, such as admin. This key is used to sign and verify external JWTs.

ksctl tokens rotate-auth-key --type ecdsa --curve p256

Copy

Note

CipherTrust Manager version 2.15 onwards, for fresh installations, the default token authentication key type is ES256. Therefore, key rotation is not required.

ksctl tokens list-jwks

{
    "keys": [
        {
            "crv": "P-256",
            "kty": "EC",
            "x": "b5y6sdqZpB5HcciwP_Fl0K4s3czQFG6tZwmXLAJxGH4",
            "y": "OKrI2Gg0xkBN1hJTO1Ai7uRBmXiYbm18qgWJHw1zW-c"
        }
    ]
}

Set SSO Access ID

To set the SSO access ID in CipherTrust Manager to access ID of authentication method created by you in Akeyless:

1. Login to CipherTrust Manager GUI as an application administrator.

2. Navigate to Admin Settings > Akeyless Config.

3. In the SSO Access ID field, enter the Access ID of authentication method created by you.

4. Click Save.

Warning

Do not edit the Akeyless Connection field. This is automatically populated with the autogenerated Akeyless gateway connection.

Configure the Akeyless gateway for Using CipherTrust Manager Customer Fragment

To allow CipherTrust Manager users to use the CipherTrust Manager generated customer fragment for protecting Akeyless secrets:

1. Navigate to Gateways and select the defaultCluster.

2. In the Gateway URL (Configuration) field, enter the Akeyless gateway URL preceded by https://. Example, https://<ciphertrust_manager_hostname>/akeyless.

3. Click the ellipsis (...) button on the right and select Manage Gateway.

4. Select Access Permissions and click Add.

5. Provide a meaningful in the Name field.

6. From Auth Method* drop-down, select the OAuth2.0/JWT authentication method created by you.

7. Click Next.

8. In Permission Settings, select Admin (default) or Custom option.

   

   Note

   The Admin option give permissions to all CipherTrust Manager users for using the customer fragment.

   You can adjust permission settings to restrict customer fragment usage to fewer CipherTrust Manager users using both CipherTrust Manager GUI and Akeyless console. To do this with Akeyless console, select Custom option and enable Zero Knowledge Encryption.

9. Click Finish.

CipherTrust Manager users can now manage secrets, including protecting them with the CipherTrust Manager generated customer fragment.

Caution

To ensure static secrets, dynamic secrets, rotated secrets, and certificates are protected in the CipherTrust Manager root of trust hierarchy, we strongly recommend configuring a default protection key using the CipherTrust Manager generated customer fragment before beginning to create secrets.

To perform additional configuration, see Restrict secrets management or customer fragment access to certain users.

Configure a Default Encryption Key

Note

This configuration can also be performed through the Akeyless CLI, if set up for Gateway Admin access.

1. As a CipherTrust Manager Application Administrator, such as admin, obtain the CipherTrust Manager customer fragment by viewing the Akeyless configuration on CipherTrust Manager.

   ksctl akeyless config get

   Copy

   Retain the customer_fragment_ids value in the response.

   Example Response:

   {
       "gateway_connection_id": "aaeea264-e713-4075-b455-54e33a1a4518",
       "sso_access_id": "p-lx4mgbad23is",
       "customer_fragment_ids": [
           "bbb34a30-7ca4-4717-a802-956b677f2a3d"
       ]
   }

   Copy

2. Login as any user with secrets management permissions to the CipherTrust Manager GUI, and click the Secrets Management tile to access the Akeyless console.

3. Create an encryption key associated with the customer fragment.

   1. Navigate to Items.

   2. Click New > Encryption Key > DFC.

   3. Configure the following settings:

      • Provide a Name for the encryption key.

      • In the Type dropdown, select AES256GCM.

      • In the Customer Fragment dropdown, select the ID of the CipherTrust Manager Generated Fragment, obtained in step 1.

   4. Click Finish.

4. Navigate to the Akeyless gateway Configuration Manager, located at https://<ciphertrust_manager_hostname>/akeyless, as Super Administrator. Supply the Access ID and Access Key obtained in step 1.

5. Select Defaults.

6. In the Default Encryption Key dropdown list, select the newly created encryption key.

7. Click Save Changes.

Control Which CipherTrust Manager Users Have Secrets Management and Customer Fragment Access

By default, any CipherTrust Manager user has access to Akeyless secrets management and can protect keys with the CipherTrust Manager generated customer fragment. If you want only a subset of users to access secrets this can be controlled with CipherTrust Manager groups, CipherTrust Manager domains and Akeyless Access Roles. If you want only a subset of users to use the CipherTrust Manager generated customer fragment, this can be controlled with CipherTrust Manager groups, CipherTrust Manager domains, and Akeyless Access Permissions.

Limit Secrets Management Access to a Group

1. Login to CipherTrust Manager as a user in the Users Admins or admin group.

2. Create a group for secrets management.

3. Associate desired users to that group.

4. Login with your Akeyless administrative account at https://<ciphertrust_manager_hostname>/akeyless-console/.

5. Navigate to Access Roles. Select the Access Role you initially created, or create a new one with rules to allow create, read, update, delete and list operations for Items.

6. Edit the associated Method in the first table. Add a Sub Claim corresponding to the CipherTrust Manager group, cust.groups=<ciphertrust_manager_group_name>. Click the checkmark to save.

Limit Customer Fragment Access to a Group

Note

This configuration can also be performed through the Akeyless CLI, if set up for Gateway Admin access.

1. Login to CipherTrust Manager as a user in the Users Admins or admin group.

2. Create a group for secrets management.

3. Associate desired users to that group.

4. Login with your Akeyless administrative account at https://<ciphertrust_manager_hostname>/akeyless-console/.

5. Navigate to Gateways.

6. Click the ellipsis (...) button on the right and select Manage Gateway.

7. Click the Access Permissions tab.

8. In the relevant Access Permission actions column, select Edit.

   

   Note

   This access permission was created as part of initial Gateway configuration and should display as Custom Permissions.

9. In the Allowed Users tab, add in a Claim corresponding to the CipherTrust Manager group, cust.groups=<ciphertrust_manager_group_name>. Click Save to confirm.

Limit Secrets Management Access to a Domain

1. Login to CipherTrust Manager as a user in the Domain Admins or admin group.

2. Create a new domain or identify an existing domain for secrets management. Copy the ID of that domain.

   

   Note

   You can only use the domain ID for Akeyless Access Role configuration. You cannot use the domain name.

3. Add desired users to that domain.

4. Login with your Akeyless administrative account at https://<ciphertrust_manager_hostname>/akeyless-console/.

5. Navigate to Access Roles. Select the Access Role you initially created, or create a new one with rules to allow create, read, update, delete and list operations for Items.

6. Edit the associated Method in the first table. Add a Sub Claim corresponding to the CipherTrust Manager domain, cust.domain_id=<domain_id_value>. Click the checkmark to save.

Limit Customer Fragment Access to a Domain

Note

This configuration can also be performed through the Akeyless CLI, if set up for Gateway Admin access.

1. Login to CipherTrust Manager as a user in the Domain Admins or admin group.

2. Create a new domain or identify an existing domain for secrets management. Copy the ID of that domain.

   

   Note

   You can only use the domain ID for Akeyless Access Role configuration. You cannot use the domain name.

3. Add desired users to that domain.

4. Login with your Akeyless administrative account at https://<ciphertrust_manager_hostname>/akeyless-console/.

5. Navigate to Gateways.

6. Click the ellipsis (...) button on the right and select Manage Gateway.

7. Click the Access Permissions tab.

8. In the relevant Access Permission actions column, select Edit.

   

   Note

   This access permission was created as part of initial Gateway configuration and should display as Custom Permissions.

9. In the Allowed Users tab, add in a Claim corresponding to the CipherTrust Manager domain, domain_id=<domain_id_value>. Click Save to confirm.

Allow Other Users Access to the Customer Fragment

In some cases, applications or users require access to the CipherTrust Manager customer fragment, without also requiring CipherTrust Manager user credentials. In these cases an application only needs to manage Akeyless secrets with Zero-Knowledge encryption, but doesn't need to access any other CipherTrust Manager functionality.

Prerequisites

• A dedicated API key authentication method.

• An Access Role associated to the authentication method, with Items rules to allow create, read, update, delete, and list operations.

Allow Access to the Customer Fragment

1. Login to the Akeyless console https://<ciphertrust_manager_hostname>/akeyless-console/ with the Gateway-Admin account. Supply the Gateway Admin Access ID and Access Key.

2. Navigate to Gateways and select the defaultCluster.

3. In the Gateway URL (Configuration) field, enter the Akeyless Gateway URL preceded by https://. For example, enter https://<ciphertrust_manager_hostname>/akeyless. Click the checkmark to confirm.

4. Click the ellipsis (...) button on the right and select Manage Gateway.

5. Select Access Permissions and click Add.

6. Click New.

7. Enter a meaningful Name, select the desired authentication method for the Auth Method, and click Next.

8. Select Custom Permissions Settings, enable Zero Knowledge Encryption, and click Finish.

Managing Multiple Customer Fragments in CipherTrust Manager

Note

• Make sure to enable the secrets-manager service (Admin Settings > Services) before working on customer fragments. One customer fragment is created by default when you enable the secrets-manager service.

• Creating or deleting a customer fragment triggers a gateway restart across all nodes of a cluster.

CLI

Create Customer Fragment

Syntax

ksctl akeyless customer-fragment create --name <customerFragmentName> --desc <customerFrgamnetDescription> --akeyless-cf-id <customerFragmentAkeylessID> --cf-material <customerFragmentMaterial> --exportable true/false

Copy

If you omit --exportable, it will be considered false by default.

Request

ksctl akeyless customer-fragment create --name test-cf --exportable true

Copy

Response

{
    "id": "d0c77b14-d9be-4017-9ee6-424811d9a459",
    "uri": "kylo:kylo:solo:customer-fragments:d0c77b14-d9be-4017-9ee6-424811d9a459",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2024-07-11T07:40:32.004837Z",
    "name": "test-cf",
    "akeyless_cf_id": "",
    "exportable": true
}

Copy

Note

Customer fragments can also be created using --cf-json-file. Precedence is given to individual flags if both .json file and flags are provided in the command.

View Customer Fragment

Syntax

ksctl akeyless customer-fragment list --id/name/akeyless-cf-id <customerFragmentID/customerFragmentName/customerFragmentAkeylessID>

Copy

Request

ksctl akeyless customer-fragment list

Copy

Response

{
    "skip": 0,
    "limit": 10,
    "total": 2,
    "resources": [
        {
            "id": "d0c77b14-d9be-4017-9ee6-424811d9a459",
            "uri": "kylo:kylo:solo:customer-fragments:d0c77b14-d9be-4017-9ee6-424811d9a459",
            "account": "kylo:kylo:admin:accounts:kylo",
            "createdAt": "2024-07-07T18:51:21.03644Z",
            "name": "test-cf",
            "exportable": false
        },
        {
            "id": "9a5bb6f6-2eb9-4192-8d8f-d64603994b2b",
            "uri": "kylo:kylo:solo:customer-fragments:9a5bb6f6-2eb9-4192-8d8f-d64603994b2b",
            "account": "kylo:kylo:admin:accounts:kylo",
            "createdAt": "2024-07-07T18:51:24.377312Z",
            "name": "CipherTrust Manager's default customer fragment",
            "description": "CipherTrust Manager generated fragment",
            "exportable": true
        }
    ]
}

Copy

Delete Customer Fragment

Syntax

ksctl akeyless customer-fragment delete --id/name <customerFragmentID/Name>

Copy

Request

ksctl akeyless customer-fragment delete --name test-CF

Copy

Response

Customer fragment is deleted successfully with no response.

GUI

Create Customer Fragment

1. Log on to the CipherTrust Manager GUI as an Application Administrator.

2. Navigate to Admin Settings > Akeyless Config.

3. Go to CUSTOMER FRAGMENTS expandable list. Click Create Customer Fragment.

4. Enter Customer Fragment Name and Description (optional).

5. Click Save. The customer fragment will be created as shown below.

   

View Customer Fragment

1. Log on to the CipherTrust Manager GUI as an Application Administrator.

2. Navigate to Admin Settings > Akeyless Config.

3. Go to CUSTOMER FRAGMENTS expandable list. It displays the list of customer fragments as shown below.

   

Delete Customer Fragment

1. Log on to the CipherTrust Manager GUI as an Application Administrator.

2. Navigate to Admin Settings > Akeyless Config.

3. Go to CUSTOMER FRAGMENTS expandable list. Select the desired customer fragment.

4. Click the ellipsis on the right side of a customer fragment and click Delete as shown below.

   

Note

The CipherTrust Manager 2.18 release onward, a new parameter akeyless-cf-id is introduced. The akeyless-cf-id is used to access the associated customer fragments on the Akeyless gateway. For existing fragments, the akeyless-cf-id will be empty. In such cases, the "resource ID" of the CipherTrust Manager will be used to access the customer fragments.

For imported customer fragments to access the existing DFC keys and secrets on the Akeyless gateway, the akeyless-cf-id must match the "unique ID" of the customer fragment on the gateway and be associated with the correct "cf-material".

The cf-material represents the value of a customer fragment and is a Base64-encoded string consisting of 88 characters. This string is used to create a customer fragment with custom secret material. Users can provide their cf-material using this field. If the cf-material is not provided, it will be automatically generated on the CipherTrust Manager.

Importing Customer Fragments

Import external customer fragments generated through Akeyless CLI/GUI on the CipherTrust Manager. The customer_fragments.json file can be downloaded from the Akeyless Gateway under Zero Knowledge Encryption.

Below is the sample customer_fragments.json file:

{
  "customer_fragments": [
   {
     "name": "imported-cf",
     "description": "this is imported cf",
     "value": "J04y/ggm5p00JhWoVqbedwgH9uEj5xtvTjroNw+TF2jhxMI929+aycL77jvmusi0ZQXRM4a23EMJV4nOtCfa7Q==",
     "id": "cf-xb2bvoviulwhmvq6cs7l",
     "fragmentType": "standard",
     "keyLabel": ""
   }
  ]
}

Caution

• In case of a "name" conflict, the import of the customer fragments with the conflicting names will fail.

• In case of mixed version cluster of CipherTrust Manager 2.17 and 2.18 nodes, it is not recommended to use the imported customer fragments for creating DFC keys and secrets on the CipherTrust Manager 2.17 nodes.

Note

• In case of empty name, the value of ID is taken as the default name.

• The customer fragments of type Standard are allowed to be imported.

• Import of maximum 50 customer fragments is allowed at once.

ksctl akeyless customer-fragment import --json-file <path-to-customer_fragments.json-file>

ksctl akeyless customer-fragment import --json-file ./customer_fragments.json

{
    "total": 1,
    "success": 1,
    "failures": 0,
    "customer_fragments": [
       {
            "id": "cf-xb2bvoviulwhmvq6cs7l",
            "name": "imported-cf",
            "description": "this is imported cf",
            "status": "success"
       }
]

Exporting Customer Fragments

This feature allows you to export pre-existing customer fragments from CipherTrust Manager to standalone Akeyless users. This helps to use the same customer fragments across multiple standalone Akeyless gateways, providing flexibility to manage and reuse them across different environments.

Syntax (To export all the customer fragments)

ksctl akeyless customer-fragment export

This command will export all customer fragments where the exportable field is set to true.

Example 1

ksctl akeyless customer-fragment export

Response 1

{
    "customer_fragments": [
            {
                    "id": "0490f2d1-c687-4c8f-9b38-284f98af2878",
                    "name": "test1",
                    "value": "vu6YAr7HBEe6dG9h5+MOJqX+nKjcbdvn4Y21vR8Guyr8jFBwQWHtj3KbDOJ4hz3C7dqtwnMRtW7X/TvAeDXcRA==",
                    "description": ""
            }
    ]
}

Syntax (Export using JSON file)

ksctl akeyless customer-fragment export --cfs-json-filename <jsonFileName>

Example 2

ksctl akeyless customer-fragment export --cfs-json-filename test.json

A new json file called "test.json" will be created with all the Customer fragments with exportable field set to true.

Obtain Gateway-Admin Credentials

Obtain the Gateway-Admin credentials using the following steps:

1. Navigate to Users & Auth Methods and click the pre-created Gateway-Admin auth method.

2. Click Reset Access Key.

3. Type Gateway-Admin and click Reset Access Key to confirm.

4. Save the Access ID and Access Key credentials, which are returned. These credentials might be required for future gateway configuration tasks.

   

   Caution

   Resetting the Access Key to obtain the Gateway-Admin credentials will make the Akeyless connection created during initial configuration invalid. The connection needs to be updated with the new Access Key followed by services restart for the Akeyless gateway to continue working.

Configuring Akeyless CLI Access for the Gateway Admin

Gateway Admins can use the Akeyless CLI on a client computer to do follow-on configuration of the Akeyless gateway, such as adding a default protection key that uses the CipherTrust Manager-generated customer fragment.

The required steps depend on the CipherTrust Manager web interface certificate.

• In a production configuration, the CipherTrust Manager web interface certificate would be signed by an certificate authority (CA) external to the CipherTrust Manager. As well, a hostname consistent with the web interface certificate would be allocated for the CipherTrust Manager in your organization's DNS server. For these setups, you can proceed directly to steps for all web interface configurations.

• By default, a local CipherTrust Manager CA issues the web interface's server certificate, and the certificate values are not suitable to register a hostname in a DNS server. This interface configuration is recommended for testing purposes only. For these setups, there are additional steps needed to install the Akeyless CLI.

Steps for Default Test Web Server Certificate Configuration

1. As a CipherTrust Manager user in the admin group, download the web interface certificate chain for the web interface to a file.

   ksctl interfaces certificate get --name web --icertfile web-ciphertrustmanager-local.pem

   Copy

2. Set an environment variable AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE to define the downloaded certificate file as trusted for the Akeyless CLI connection.

   Windows

   set AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE=<path_to_certificate_chain_file>

   Copy

   Example:

   set AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE=web-ciphertrustmanager-local.pem

   Copy

   Linux

   export AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE=<path_to_certificate_chain_file>

   Copy

   Example:

   export AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE=web-ciphertrustmanager-local.pem

   Copy

3. Resolve the hostname to the subject alternative name on the local operating system.

   Windows

   Add an entry to C:\Windows\System32\drivers\etc\hosts file with the CipherTrust Manager IP address and the subject alternative name.

   Example

   172.31.21.55 web.ciphertrustmanager.local

   Linux

   Syntax

   cat /etc/hosts 127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
   ::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 <ciphertrust_IP_address> <certificate_subject_alternative_name>

   Copy

   Example

   cat /etc/hosts 127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
   ::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 172.31.21.55 web.ciphertrustmanager.local

   Copy

Proceed to steps for all web interface configurations.

Steps for All Web Interface Configurations

1. Set an environment variable AKEYLESS_GATEWAY_URL to define the CipherTrust Manager Akeyless Gateway URL in relation to the server certificate. The variable depends on whether the client is hosted on Windows or Linux. You require the Subject Alternative Name in the web interface server certificate. For the default web interface configuration, this value is web.ciphertrustmanager.local.

   

   Caution

   Always include the trailing slash in the environment variable.

   Windows

   set AKEYLESS_GATEWAY_URL=https://<subject_alternative_name>/akeyless-api/

   Copy

   Default web interface server certificate:

   set AKEYLESS_GATEWAY_URL=https://web.ciphertrustmanager.local/akeyless-api/

   Copy

   Linux

   export AKEYLESS_GATEWAY_URL=https://<subject_alternative_name>/akeyless-api/

   Copy

   Default web interface server certificate:

   export AKEYLESS_GATEWAY_URL=https://web.ciphertrustmanager.local/akeyless-api/

   Copy

2. Download and install the latest Akeyless CLI.

3. Create a profile when prompted using the gateway Admin's Access ID and Access Key.

Tip

If you use a CA specific to your organization to sign the web interface certificate, and the Akeyless CLI doesn't connect to the gateway, this could indicate that the CA is at a nonstandard location that the Akeyless CLI can't find. Try setting the AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE environment variable as the path to your organization CA.

Akeyless Browser Extension

The akeyless browser extension is a secrets management tool that allows you to create and view secrets on the go.

The akeyless browser extension can be used to create and view static secrets. The static secrets are key/value pairs that you create and update manually, such as passwords and API tokens. Any text-based items can be stored within their original format, including config files, JSON, YAML, and so on.

It also allows you to view the rotated and dynamic secrets. The rotated secrets enable you to protect the credentials for privileged-user accounts such as an Administrator account on a Windows server, a root account on a Linux server, or an Admin account on a network device, by resetting its password, whereas, the dynamic secrets are generated every time they are accessed, using permissions you've defined in advance. In this way, users can access a resource for a temporary period with a defined set of permissions.

The extension can be installed in the browser such as Firefox, Google Chrome, and Microsoft Edge. When you log in to akeyless with valid credentials, you can access and utilize secrets from that account.

Note

• The password management functionality is disabled for the Thales infrastructure. If a user tries to store the passwords using the extension, it throws an error.

• The extension is not supported with the credentials created in the single-tenant environment.

• Secrets that are protected by a customer fragment can't be viewed inside the extension.

For more details, click here.

Akeyless Single Tenant Infrastructure

Single-tenancy is an architecture in which a single instance of a software application and supporting infrastructure serves one customer.

The default Akeyless gateway always points to the vault.akeyless.io URL. The following parameters have been introduced for the users having single tenant infrastructure to perform the akeyless cloud operations:

For new sign ups when CSM is not configured

ksctl akeyless config modify --akeyless-signup-url <akeyless-infrastructure-url>

{

    "akeyless_signup_url": <akeyless-infrastructure-url>,

    "customer_fragment_ids": [

        "36871b61-a57a-45be-b464-ec3f349f4d63"

    ]

}

Reconfigure existing CSM configuration to use single tenant infrastructure

ksctl connectionmgmt akeyless create --name test-connection --akeyless-key-id p-36zh053am --akeyless-key 0q4Lsh2iUHARpSaMvIeYaEgMuj6o2TN1RM --akeyless-url <akeyless-infrastructure-url>

{
    "id": "51ee0d98-165b-438f-9e1c-4444e5e5e01a",
    "uri": "kylo:kylo:connectionmgmt:connections:test-connection-51ee0d98-165b-438f-9e1c-4444e5e5e01a",
    "account": "kylo:kylo:admin:accounts:kylo",
    "createdAt": "2023-11-01T10:18:29.79939315Z",
    "updatedAt": "2023-11-01T10:18:29.798182064Z",
    "service": "akeyless",
    "category": "cloud",
    "last_connection_ok": null,
    "last_connection_at": "0001-01-01T00:00:00Z",
    "name": "test-connection",
    "access_key_id": "p-36zh053am",
    "akeyless_url": "<akeyless-infrastructure-url>"
}

Note

• You may encounter the "502 Bad Gateway" error when connecting to Akeyless from a CipherTrust Manager in the following scenarios:

  • After restarting the CipherTrust Manager or the Akeyless gateway.

  • After updating akeyless-signup-url or configuring gateway connection in the gateway configuration endpoint.

  To establish a connection, first check the internet connectivity and retry after some time.

• Akeyless gateway version 4.15.0 onward, you can log on to the Akeyless console using Access IDs generated in a different environment, even if akeyless-signup-url on the CipherTrust Manager is configured for a specific environment such as a single-tenant infrastructure. This is allowed only for Access IDs created in the year 2024 or later. Earlier, logins were only permitted for Access IDs belonging to a specific environment configured through akeyless-signup-url.

• The signup process remains the same and still creates new accounts in the environment specified by akeyless-signup-url.

• For auto-detection of Access IDs generated on a newly deployed single-tenant infrastructure, update the Akeyless gateway. Until the software is updated, the akeyless URL field serves its purpose and is used for identification.

Mapping CipherTrust Manager Domains to Akeyless Resources

On CipherTrust Manager, a domain is a logical division that isolates users and resources. Resources such as keys are private to their specific domain and cannot be accessed across domains.

Before proceeding to the next steps, we recommend you to get familiar with the following terms:

• Access Roles - limit access rights for users. It is a way to grant specific permissions to users on secrets, encryption keys, targets, authentication methods, and so on. Access roles are very similar to the groups in the CipherTrust Manager.

• Directory Structure - provides logical separation of akeyless resources. The concept of directory structure is logically similar to the domains in the CipherTrust Manager.

• Sub Claims - for some of the authentication methods such as JWT/OIDC, and LDAP that contain attribute-based access control (ABAC), also known as policy-based access control, as part of the given signed token, you can restrict the authorizations of the associated role to these specific claims or attributes. In other words, only clients whose token contains these sub claims (in the case of JWT/OIDC) or attributes (in the case of SAML) will be allowed to access the rules defined in the role.
  For more details, refer to Akeyless documentation.

Tip

In this section, the terms directory and domain will be used interchangeably.

Akeyless allows you to create separate access roles for different domains and for the associated users of that domain. While creating access roles, you can add these access roles to different directory structures to achieve a logical separation.

To create access roles, perform the following steps:

Note

Only the Super Administrator can create Access Roles.

On the CipherTrust Manager

1. Log on to the CipherTrust Manager GUI as an Application Administrator.

2. Configure the Single sign-on (SSO) flow. Refer to Configure Akeyless gateway for details.

On Akeyless Console

1. Navigate to Access Roles. Click New to create an access role.

2. On the Create Role screen, add Name, Location, and Description. The Location field is used to create a directory structure. If you don't provide any directory name in Location, the role will be created in the root directory.

3. Create directories as required, one for each domain.

   Now, separate directories are created for each domain and domain-users can only access the particular set of permissions that are defined within those directories. This allows creation of distinct permission sets for the specific users associated with that domain.

To create a permission set for a particular directory, perform the following steps:

1. Navigate to the domain directory and select the access role created inside it as created in the above steps.

2. Click Associate to configure an authentication method and sub claims. This step creates an association between the access role and the authentication method. Each user authenticating through this authentication method will be assigned permission set of this access role if the sub claim condition satisfies.

3. On the Associate Auth Method screen, select Auth Method from the drop-down list that allows SSO login and add Sub Claims corresponding to the CipherTrust Manager domains or groups.

   For domain

   Syntax

   cust.domain_id = <ciphertrust_manager_domain_ID>

   Copy

   Example

   cust.domain_id = 53c5aa3b-1e75-4684-b644-512e483fe883

   Copy

   Similarly, you can add a Sub Claim corresponding to the CipherTrust Manager group:

   Syntax

   cust.groups = <ciphertrust_manager_group_name>

   Copy

   Example

   cust.groups = Key Admins

   Copy

   You can get domain id and group information from the CipherTrust Manager.

4. Click Add to add rules for Items. You must add at least one set of permissions to make this work.

Now the permission set is created for domain users inside the akeyless directory.

Let's see some of the use cases.

Use case 1

If you want to define an access role for users who are members of a particular domain and a group.

You can add multiple sub claims in the single associated auth-method.

Syntax

cust.domain_id = <ciphertrust_manager_domain_ID>
cust.groups = <ciphertrust_manager_group_name>

Example

To generate domain specific key permissions, let's create a domain say "domain-1" and associate it with "Key Admins" groups.

cust.groups = Key Admins
cust.domain_id = <domain id of the domain-1>

Use case 2

Multiple domains can also be linked to a single access role. As a result, a single access role can handle a set of permissions for many domains, and all users in each domain can access akeyless resources.

To add multiple attributes of the same type such as cust.domain_id or cust.groups in a single access role association, you can perform multiple associations (using Associate button) as shown below:

Association 1

cust.domain_id = <ciphertrust_manager_domain_ID>

Association 2

cust.domain_id = <ciphertrust_manager_domain_ID>

Association 3

cust.domain_id = <ciphertrust_manager_domain_ID>

Association 4

cust.domain_id = <ciphertrust_manager_domain_ID>

Managing Multiple Customer Fragments in Akeyless Console

The previous section describes how the CipherTrust Manager domains are mapped to the Akeyless directories using the appropriate sub-claims. This allows separation of resources but all the protection keys (used to encrypt secrets) could only use a single CipherTrust Manager generated customer fragment created during the system startup.

To attain a granular control, users can now create multiple customer fragments and multiple protection keys can be created using these fragments. These fragments will be accessible in the Akeyless gateway.

Note

The customer fragments in the CipherTrust Manager are not domain scoped and can be created/managed only in the root domain. A user should belong to the admin group in the root domain to perform the customer fragment operations.

Prerequisites

• Akeyless gateway is configured. Refer to Configure Akeyless gateway for details.

• CipherTrust Manager domains are mapped to the Akeyless resources. Refer to Mapping CipherTrust Manager Domains to Akeyless Resources for details.

Providing Customer Fragment Access to CipherTrust Manager Admin

To provide customer fragment access to the CipherTrust Manager admin:

1. Sign in to the Akeyless console as the Super Admin or gateway Admin.

2. Navigate to the Gateways tab and select default gateway.

3. Go to the Access Permissions tab and click Add.

4. Add a name to the access permission and select SSO as the Auth Method. The CipherTrust Manager uses this method for authentication.

5. Add the sub-claims: cust.groups = admin and cust.domain_id = 00000000-0000-0000-0000-000000000000.

6. In the Permissions Settings section, select Zero Knowledge Encryption. This will grant the CipherTrust Manager administrator (in the root domain) access to use all the customer fragments.

Limiting DFC Key Access to Directories

Assume a scenario with two CipherTrust Manager domains dom1 and dom2 with all the mappings in place with Akeyless directories and access roles.

1. Create two customer fragments for each of these domains. Name these customer fragments as dom1 CF and dom2 CF.

   Refer to Step 13 (Manage customer fragments) of the Configure Akeyless gateway section for details.

   The Akeyless configurations should be auto-updated and start showing IDs of the above created fragments in the customer_fragment_ids parameter. Also, the fragments should be visible in the Zero Knowledge Encryption section on the Akeyless gateway.

2. Sign in as the CipherTrust Manager administrator (in the root domain) and click CSM tile.

3. On the Items section in the Akeyless console, click New > Encryption Key > DFC.

4. Add a relevant name, description, and type AES256 for the DFC key.

5. Set the location of the key as /dom1.

6. Select customer fragment dom1 CF from the drop-down list.

7. Repeat the above steps for creating a DFC key in dom2.

Now sign in to the CipherTrust Manager as a user in dom1 who has access to the Akeyless resources in the dom1 directory and perform the following steps:

1. Click CSM tile on the products page.

2. Create a new secret. While selecting the protection key for this secret, the DFC key created in the previous steps can be viewed. Note that only the key created in the dom1 directory will be visible.

3. Repeat the above steps for user in dom2.

This way the resources created in any of the domains (dom1 and dom2) can only be decrypted by assigned DFC keys, which would be using their own unique customer fragment.