Configure Secrets Management

Some configuration is needed to set up the Akeyless Gateway before you can manage secrets.

Prerequisites

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

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

Configure Akeyless Gateway

1. Sign up for an Akeyless account with administrative level permissions.

   This 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. Click the Sign up link in the upper right.

   3. Enter an email address.

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

      The account credentials are displayed in a browser window.

   5. Capture the Access ID and Access Key. There is an option to save these values to CSV, if desired. These are required for necessary Akeyless Gateway configuration.

2. As a CipherTrust Manager Application Administrator, such as admin, rotate the CipherTrust Manager authentication key to an ECSDA key.

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

   This key is used to sign and verify external JWTs.

3. Isolate the public key value and reformat for Akeyless console.

   In CipherTrust Manager, the you can view the public key value with ksctl tokens list-auth-keys command. The public key value is displayed in a JSON attribute called public_key_jwk. Akeyless console needs this value in an array called keys.

   Akeyless Console Syntax

   {
     "keys": [
   <value of `public_key_jwk` attribute>
     ]
   }
   

   Example Reformatting

   In this example, the public_key_jwk attribute is obtained with ksctl, and then reformatted in a text editor.

   ## Obtain the public key value
   
   ksctl tokens list-auth-keys
   
   {
       "skip": 0,
       "limit": 10,
       "total": 1,
       "resources": [
           {
               "id": "7e99444d-f511-4a75-908f-f3cc90801e4e",
               "type": "ecdsa",
               "public_key_pem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEb5y6sdqZpB5HcciwP/Fl0K4s3czQ\nFG6tZwmXLAJxGH44qsjYaDTGQE3WElM7UCLu5EGZeJhubXyqBYkfDXNb5w==\n-----END PUBLIC KEY-----\n",
               "public_key_jwk": {
                   "crv": "P-256",
                   "kty": "EC",
                   "x": "b5y6sdqZpB5HcciwP_Fl0K4s3czQFG6tZwmXLAJxGH4",
                   "y": "OKrI2Gg0xkBN1hJTO1Ai7uRBmXiYbm18qgWJHw1zW-c"
               },
               "createdAt": "2023-06-21T12:53:40.23849Z",
               "updatedAt": "2023-06-21T13:01:24.872168Z"
           }
       ]
   }
   
   ## Example reformatting
   
   {
     "keys": [
       {
         "crv": "P-256",
         "kty": "EC",
         "x": "b5y6sdqZpB5HcciwP_Fl0K4s3czQFG6tZwmXLAJxGH4",
         "y": "OKrI2Gg0xkBN1hJTO1Ai7uRBmXiYbm18qgWJHw1zW-c"
       }
     ]
   }
   

4. Register the ECDSA signing key with Akeyless and create objects to authenticate CipherTrust Manager users to Akeyless console.

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

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

      Note

      We recommend deleting the User-Admin role, as it is not needed. The new Oauth 2.0/JWT method controls Akeyless permissions for CipherTrust Manager users.

   3. Create an OAuth2.0/JWT authentication method. The following settings are required:

      • A Name must be provided.

      • The JSON option must be selected.

      • The JWKs JSON field must contain the ECDSA public key value. Copy and paste the keys array created in step 3.

      • Set a value for Unique Identifier and it should be unique. For example, "sub".

      You can optionally change the default JWT TTL (in minutes) from the default value. This controls the expiry time for an Akeyless token issued for CipherTrust Manager users.

   4. Click Save.

   5. Retain the Access ID value of this authentication method, as this is needed to edit the Akeyless configuration on CipherTrust Manager.

   6. Navigate to Access Roles.

      Note

      You must associate the new auth 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 UI and Akeyless console to restrict secrets management to fewer CipherTrust Manager users, if desired.

   7. Click New to create a new role, provide a Name, and click Create Role.

   8. Select the tabs for Secrets & Keys, Access Roles, Auth Methods, and Targets, and click + Add to add rules. Add recursive rules to allow create, read, update, delete and list operations. Click Add.

      Caution

      Do not allow the 'Deny' operation. This overrides all other operations permissions, and breaks the CipherTrust Manager integration.

   9. Associate the new auth method to the new access role. Click + Associate, select the auth method name from the Auth Method dropdown. Click save.

5. Obtain the Gateway-Admin access key.

   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 are needed to create the CipherTrust Manager connection, and for future Gateway configuration tasks.

6. As a CipherTrust Manager user with permissions to manage connections, such as admin, create the CipherTrust Manager connection to the Akeyless Vault Platform. Provide the Access ID and the Access Key values obtained in the previous step, associated with the Gateway-Admin authentication method.

   ksctl connectionmgmt akeyless create --name <name> --akeyless-key-id  <akeyless_gateway_admin_access_id> --akeyless-key <akeyless_gateway_admin_access_key>
   

   Retain the connection id value which is returned.

7. Test the connection.

   ksctl connectionmgmt akeyless test --id <connection_id>
   

8. Edit the Akeyless configuration. Set the the gateway-connection-id to the ID of the connection created in step 6. Set the sso-access-id to the Akeyless access ID associated with the OAuth2.0/JWT authentication method created in step 4.

   ksctl akeyless config modify --gateway-connection-id <connection-id> --sso-access-id <sso_access_id>
   

9. Restart the CipherTrust Manager services. Type y to confirm the action.

   ksctl services restart
   

10. Once CipherTrust Manager GUI is available again, login as any user.

    Ensure that the Secrets Management tile is enabled.

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

11. Allow CipherTrust Manager users to use the CipherTrust Manager generated customer fragment to protect Akeyless secrets.

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

    2. Navigate to Gateways and select the defaultCluster.

    3. In the Gateway URL (Configuration) field, enter the CipherTrust Manager URL preceded by https://. For example, enter https://ciphertrust.mycompany.com. Click the checkmark to confirm.

    4. Click the Access Permissions tab.

    5. Click New.

    6. Enter a meaningful Name, select the OAuth2.0/JWT authentication method created in step 4 for the Auth Method, and click Next.

       Note

       These steps set up permissions for all CipherTrust Manager users to use the customer fragment. You can adjust settings on both CipherTrust Manager UI and Akeyless console to restrict customer fragment usage to fewer CipherTrust Manager users, if desired.

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

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

You can perform additional configuration if needed:

• Restrict secrets management or customer fragment access to certain users, if needed.

Configure a Default Encryption Key

This configuration can also be performed through the Akeyless CLI, if [set up for Gateway Admin access](#configuring-akeyless-cli-access-for-the-gateway-admin).

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
   

   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"
       ]
   }
   

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

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

   1. Navigate to Secrets & Keys.

   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.

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 Secrets & Keys.

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

This configuration can also be performed through the Akeyless CLI, if [set up for Gateway Admin access](#configuring-akeyless-cli-access-for-the-gateway-admin).

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 to the Akeyless console https://<ciphertrust_manager_hostname>/akeyless-console/ with the Gateway-Admin account. Supply the Access ID and Access Key.

   Note

   This account was used to create the CipherTrust Manager Akeyless connection during initial Akeyless Gateway configuration.

5. Navigate to Gateways and click the Access Permissions tab.

6. 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.

7. 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 Secrets & Keys.

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

This configuration can also be performed through the Akeyless CLI, if [set up for Gateway Admin access](#configuring-akeyless-cli-access-for-the-gateway-admin).

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 to the Akeyless console https://<ciphertrust_manager_hostname>/akeyless-console/ with the Gateway-Admin account. Supply the Access ID and Access Key.

   Note

   This account was used to create the CipherTrust Manager Akeyless connection during initial Akeyless Gateway configuration.

5. Navigate to Gateways and click the Access Permissions tab.

6. 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.

7. 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 Secrets & Keys 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 CipherTrust Manager URL preceded by https://. For example, enter https://ciphertrust.mycompany.com. Click the checkmark to confirm.

4. Click the Access Permissions tab.

5. Click New.

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

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

View CipherTrust Manager Generated Customer Fragment

The CipherTrust Manager generated customer fragment ID is visible in both the CipherTrust Manager CLI and the Akeyless Gateway Configuration Manager.

Viewing in CipherTrust Manager CLI

As a CipherTrust Manager Application Administrator, such as admin, view the Akeyless configuration on CipherTrust Manager.

ksctl akeyless config get

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"
    ]
}

Viewing in Akeyless Gateway Configuration Manager

1. Login to https://<ciphertrust_manager_hostname>/akeyless/ with an Akeyless account with administrative level permissions. Supply the Access ID and Access Key.

   Note

   An account with these permissions was created as part of initial Akeyless Gateway configuration.

2. Navigate to Zero Knowledge Encryption.

   The CipherTrust Manager generated fragment is listed first in the table, with the description "CipherTrust Manager generated fragment".

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
   

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>
   

   Example:

   set AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE=web-ciphertrustmanager-local.pem
   

   Linux

   export AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE=<path_to_certificate_chain_file>
   

   Example:

   export AKEYLESS_TRUSTED_TLS_CERTIFICATE_FILE=web-ciphertrustmanager-local.pem
   

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>
   

   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
   

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/
   

   Default web interface server certificate:

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

   Linux

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

   Default web interface server certificate:

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

2. Download and install the latest Akeyless CLI.

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