Secrets Management

Harness includes a built-in Secrets Management feature that enables you to store encrypted secrets, such as access keys, and use them in your Harness applications. Some key points about Secrets Management:

  • Secrets are always accessed/decrypted at the time when they are needed, and at no time are they stored unencrypted.
  • Harness Manager does not have access to your key management system, and only the Harness Delegate, which sits in your private network, has access to it. Harness never makes secrets management accessible publicly. This adds an important layer of security.

This topic discusses the following:

Use Harness or Third-Party Secret Management

You can choose to use your own secret management solution or the Harness Secrets Management built-in solution that leverages the Harness account on AWS KMS.

Below is a diagram representing how secrets are used with Harness.

KMS is not storage. As a Key Management System, KMS exchanges plaintext and encrypted keys. If you supply an encrypted key, KMS returns a plaintext key. And vice versa.

Harness only sends encrypted data to KMS. Your browser sends data over HTTPS to the Harness Manager. The Harness Delegate retrieves data as encrypted data from the Harness Manager over HTTPS. The Delegate exchanges a key pair over an encrypted connection with KMS. The Harness Delegate uses the encrypted key and encrypted secret and then discards them. The keys never leave the Delegate.

To Add a Secret Manager

When you create a new secret, the secret goes to the default Secret Manager. When a secret is created in Harness, Harness knows which secret manager the secret is created with. When Harness reads the secret, the query will be targeted to the Secret Manager the secret is associated with. It does not need to be from the default Secret Manager.

You can add your own secrets manager to Harness.

To add a secrets manager, do the following:

  1. Mouseover Continuous Security, and click Secrets Management. The Secrets Management page appears.
  2. Click Configure Secret Managers. The configured secret managers are displayed. The default is identified with a checkmark.
  3. Click Add Secret Manager. The Configure Secret Manager appears.
  4. Provide the account access information for the new secret manager. See the different options below.
  5. In Renew Interval Hours, select how often the secrets in the Secret Manager are reloaded by the Harness delegate.
  6. Check Use as default secret manager to set this secret manager as the default.
  7. Click SUBMIT.

Harness SecretStore (AWS KMS)

For Harness SecretStore (AWS), you must add a Display Name, AWS Access Key, AWS Secret Key, and AWS Resource Name (ARN). You can locate these in the JSON for the Key Policy or in the AWS IAM console, under Encryption keys. For more information, see Finding the Key ID and ARN from Amazon.

HashiCorp Vault

For HashiCorp Vault, you must add a Display Name, Vault URL, and Token/App Role. For more information, see Vault documentation.

AppRole Method

The App Role option enable allows Harness Vault Secret Manager to authenticate with Vault-defined roles.

The Vault AppRole method allows multiple roles to be defined, corresponding to different applications, and each with different levels of access. To authenticate with Vault, the application is assigned a static Role ID and a dynamically generated Secret ID, which are both required to log in and fetch a Vault token.

The App Role ID and Secret ID you supply will be used by Harness to fetch a Vault Auth Token dynamically at configured intervals set in Renewal Interval.

The Vault AppRole ID used needs to have an ACL policy attached for Harness to use it. Typically, you create the policy first, then create the AppRole and attach the policy.

If the secrets are in the default Vault folder, the policy will look like this:

path "secret/*" {
capabilities = ["create", "update", "list", "read", "delete"]
}

If the secrets are in a subfolder, such as secrets/harness, the policy will look like this:

path "secret/harness/*" {
capabilities = ["create", "list", "read", "update", "delete"]
}
path "secret/harness" {
capabilities = ["list", "read"]
}

For more information, see RoleID and Authenticating Applications with HashiCorp Vault AppRole from HashiCorp.

AWS Secrets Manager

You can use AWS Secrets Manager for your Harness secrets. AWS Secrets Manager differs from AWS KMS in that AWS Secrets Manager stores both secrets and encryption keys whereas with AWS KMS, Harness stores the secret in its Harness store and retrieves the encryption keys from KMS.

For AWS Secrets Manager, you must provide the following:

  • Display Name - Enter a name for this secret manager.
  • Access Key - The AWS Access Key ID for the IAM user you want to use to connect to Secrets Manager.
  • Secret Key - Secret Access Key corresponding to the Access Key ID.
  • Secret Name Prefix - A prefix to be added to all secrets. For example, devops will result in secrets like devops/mysecret. The prefix is not a folder name, but a prefix. Secrets Manager uses is a flat naming method.
  • Region - AWS region for the Secrets Manager.

When you are done, the dialog will look something like this:

AWS Secrets Manager Limitations
  • The content size of secrets (encrypted text or file) must be less than 7168 bytes.
  • Secret names must be alphanumeric (Vault and KMS do not have this limitation). When migrating secrets created using Vault or KMS into AWS Secrets Manager, failures might occur due to the secret name limitation. You will have to rename those secrets into an alphanumeric format before they can be transitioned into AWS Secrets Manager.

For more information, see Limits of AWS Secrets Manager from AWS.

Azure Key Vault

You can use Azure Key Vault for your Harness secrets. Azure Key Vault safeguards cryptographic keys and secrets, encrypting authentication keys, storage account keys, data encryption keys, .pfx files, and passwords.

To set up Azure Key Vault as your Harness secret manager, provide the following:

  • Display Name - Enter a name to identify the key vault.
  • Client ID - This is the Client/Application ID for the Azure app registration you are using. It is found in the Azure Active Directory App registrations. For more information, see this Quickstart doc from Microsoft.
  • Tenant ID - The Tenant ID is the ID of the Azure Active Directory (AAD) in which you created your application. This is also called the Directory ID. For more information, see Get tenant ID from Azure.
  • Subscription - Enter your Azure subscription GUID. In Azure, click Subscriptions. The list of your subscriptions is displayed along with the subscription ID. If you do not enter a GUID, the default subscription for the Client ID is used.
  • Key - Authentication key for your application. This is found in Azure Active Directory, App Registrations. For more information, see Get application ID and authentication key from Azure.
  • Vault - Click Fetch Vault and then select your vault name.

Once Azure Key Vault is set up as the default Secrets Manager, the name of any secret you save must follow the Azure Key Vault conventions.

At this time, you cannot link to pre-setup secrets in Azure Key Vault. You need to create secrets in Harness which are then saved in Azure KeyVault.

CyberArk

You can use CyberArk for your Harness secrets. CyberArk protects all privileged account passwords and SSH keys in a highly-secure central repository to prevent the loss, theft or unauthorized sharing of these credentials.

When you add CyberArk as the Harness Secrets Manager, you provide the credentials that Harness will use to retrieve secrets. Once you have CyberArk set up as the Harness Secrets Manager, you can retrieve existing secrets using queries as described in Existing CyberArk Secrets.

Fill out the following fields:

  • App ID - The unique ApplicationId of the application.
  • CyberArk URL - Enter the base URL of the server hosting CyberArk's Privileged Account Security Web Services SDK.
  • Client Certificate PEM - Paste in the user credentials certificate to use for CyberArk connections. Use pbcopy to avoid any text formatting issues.

CyberArk Limitations

When you use CyberArk as the Harness Secrets Manager, be aware that Harness is not be able to write new secrets, just read existing ones created directly via Cyberark. See Referencing Existing Secrets.

Due to CyberArk API limitations, credentials for new Connectors and Cloud Providers are encrypted and stored in the Harness SecretStore instead of CyberArk.

You cannot create Harness Encrypted Files using CyberArk.

Migrating Secrets

Secrets Management supports the ability to migrate your secrets between secret managers, in case the default secret manager is compromised.

  1. In Secrets Management, click Configure Secret Managers.
  2. Next to the secret manager you want to migrate secrets from, click Deprecate.
  3. In the Deprecate dialog, in Transition data to use, select another secret manager, and click SUBMIT.

Using Secret Management

Secret Management includes the management of connections to artifact servers and cloud providers, and several types of execution credentials. The secrets you add can be used throughout your account, and managed centrally in Secret Management.

Using Cloud Providers

In Cloud Providers, the cloud providers added to the account are listed. For each one, you can see the Run Time Usage Log and Change Log:

  • The Run Time Usage Log shows each time the cloud provider was used and by which deployments. Click a deployment name to view that specific deployment.
  • The Change Log shows each time the cloud provider was changed and by which user.

For more information, see Add Cloud Providers.

Using Connectors

Under Connectors, the Artifact Servers, Collaboration Providers, and Verification Providers that you have configured for the account are listed. For each connector, you can see the Run Time Usage Log and Change Log.

For information on adding these connectors, see Add Artifact Servers, Add Collaboration Providers, and Verification Providers.

Using Execution Credentials

The default Secret Manager for your account is used to encrypt any secrets, files, or execution credentials. Once configured, encrypted text and files are available across your account. This allows you to upload a secret once, use it everywhere, and manage it in once place.

There are several execution credential types you can add to Secrets Management.

SSH
Currently, Harness does not support OpenSSH private keys for SSH keys. Support will be added soon. To generate an SSHv2 key using OpenSSH, use ssh-keygen -t rsa -m PEM newkey. Also, ensure that the BEGIN RSA and END RSA lines are included when you paste in the key.

You will add SSH keys for use in connecting to remote servers, such as an AWS EC2 instance. For example, if you were to SSH into an EC2 instance, in a terminal, you would enter:

ssh -i "example.pem" ec2-user@ec2-76-939-110-125.us-west-1.compute.amazonaws.com

The SSH Configuration dialog provides fields where you can provide the same information.

The SSH secret you add here can be used in Harness components wherever they need to SSH into your remote server. For example, in a Harness Environment Service Infrastructure dialog, you specify Connection Attributes that use the SSH secret to connect to the target host.

To add an SSH key that can be referenced in Harness entities, do the following:

  1. In Secrets Management, click SSH.
  2. Click Add SSH Key. The SSH Configuration dialog appears.
  3. Enter a Display Name for the SSH credentials.
  4. (Required.) In User Name, provide the user name for the user account on the remote server. For example, if you want to SSH into an AWS EC2 instance, the user name would be ec2-user.
  5. Do one of the following:
    1. Click Inline SSH Key and paste in the key to use. Enter the private key file for the SSH connection.
    Do not open a .pem file in a text editor and copy and paste its contents into Inline SSH Key. Open a terminal, browse to the location of the .pem file, and use pbcopy to copy the contents of the file, like this: $ cat example.pem | pbcopy. Next, click in the Inline SSH Key field and paste the contents.
    1. Click SSH KeyFile Path (on Delegate) and specify the location of the key. This is the file path on the server running the Harness Delegate, such as /home/johndoe/example.pem.
    2. Click Password and enter the password for the user account.
  6. In Passphrase, enter in the SSH key passphrase if one is required. It is not required by default for AWS or many other platforms.
  7. In SSH Port, leave the default 22 or enter in a different port if needed.
  8. If you want to restrict the use of these SSH credentials to specific Harness components, do the following:
    1. In Usage Scope, click the drop-down under Applications, and click the name of the application.
    2. In Environments, click the name of the environment.
  9. Click TEST. The Host Connectivity Test tool appears.
  10. In Host Name, enter the host name of the remote server you want to SSH into. For example, if it is an AWS EC2 instance, it will be something like, ec2-76-939-110-125.us-west-1.compute.amazonaws.com.
  11. Click RUN. If the test is unsuccessful, you might see an error stating that no Harness Delegate could reach the host, or that a credential is invalid. Ensure that your settings are correct and that a Harness Delegate is able to connect to the server.
  12. When a test is successful, click SUBMIT.
SSH via Kerberos

Harness supports SSH server authentication using Kerberos, enabling you to SSH into a target host via the Kerberos protocol. For a quick Kerberos summary, see Explain like I’m 5: Kerberos by Lynn Root.

Field

Description

Auth Scheme

Select Kerberos.

Principal

Principal is a string that names a specific entity to which a set of credentials may be assigned. Enter the account name associated with the Kerberos account, such as johndoe.

Realm

Realm is the logical network served by a single Kerberos database and a set of Key Distribution Centers (KDCs). Typically, this is the domain where the service the user is trying to authenticate with is located.For example: US-EAST-2.COMPUTE.INTERNAL.Typically, the target host(s) that your SSH connection is intending to authenticate with via Kerberos are located in a domain name with the same name you enter in Realm. For example, ip-172-31-44-168.us-east-2.compute.internal.The realm naming convention is all uppercase letters to differentiate the realm from the internet domain, but the Realm field does not enforce the convention.

TGT Generation

Select one of the following options:

  • Key Tab File Path (on Delegate) - You can choose this option to generate a new TGT from the KDC every time you authenticate with the service. This ensures that the TGT is always valid and not expired when you try to authenticate.
  • Password - Select this option to enter a password for TGT generation.
  • None - Select this option to skip skip TGT Generation. If you select this option, you must ensure that the TGT that is on the server running the Harness delegate is always available.

Keytab File Path

This field is displayed if you select Key Tab File Path for TGT Generation.Enter the file path to the keytab file on the server running the Harness delegate. For example, /home/johndoe/a.keytab. The file is not uploaded to Harness.

When you done, the dialog will look something like this:

To use the Kerberos SSH connection to connect to a target host, you select it in SSH Connection Attributes when specifying the target host in the Service Infrastructure settings of an environment.

In this example, the target host that you want to use Kerberos authentication with is entered in Host Name(s).

Note that the domain name used to identify the hosts in the Host Name(s) field is likely to be the same as the domain name you entered in Realm when configuring the SSH connection.

WinRM Connection
For information on setting up WinRM connections in Harness, see Set Up the WinRM Connection in Harness.

You can set up a WinRM connection and then use it as a Deployment Type in an environment's Service Infrastructure.

Encrypted Text

You can encrypt any text and reference it in Harness application entities or connections.

  1. In Secrets Management, click Encrypted Text.
  2. Click Add Encrypted Text. The Add Encrypted Text dialog appears.
  3. Enter a name for the encrypted text. This is the name you will use to reference the text elsewhere in your applications.
  4. Enter a value for the encrypted text.
  5. Scope to Account - If your Harness User account is part of a User Group with the Administer Other Account Functions permission enabled, you will see the Scope to Account option. Select Scope to Account to make this encrypted text secret available to Delegate Profile scripts only. Only secrets scoped to the account are available to use in Delegate Profiles.
  6. If you want to restrict the use of the text to specific applications and environments, use Usage Scope. The encrypted text secret can be used in Workflows in Applications listed in its Usage Scope. The encrypted text secret can be used in Delegate Profiles only if the secret it is referencing is Account-level, with no Applications in its Usage Scope. For more information, see Using Secrets.
    1. In Usage Scope, click the drop-down under Applications, and click the name of the application.
    2. In Environments, click the name or type of the environment.
  7. Click SUBMIT.

Now, when you are in an application entity such as a service, you can use the encrypted text. For example:

  1. In the Configuration section of a service, click Add Variable. The Config Variable dialog appears.
  2. Enter a name for the variable, and then, in Type, select Encrypted Text.
  3. In Value, select the secret you created in Secrets Management.
  4. Click SUBMIT and the secret will be used at runtime.

For an example of how to use an Encrypted Text secret, see Using Secrets.

Encrypted Files

You can upload encrypted files and reference them across your account in the same way as encrypted text.

  1. In Secrets Management, click Encrypted Files.
  2. Click Add Encrypted File. The Add Encrypted File dialog appears.
  3. Enter a name for the encrypted file. This is the name you will use to reference the file in application entities.
  4. Click Choose File, and locate and add a file. The default Secret Manager for your account is used to encrypt the file.
  5. Scope to Account - If your Harness User account is part of a User Group with the Administer Other Account Functions permission enabled, you will see the Scope to Account option. Select Scope to Account to make this encrypted file secret available to Delegate Profile scripts only. Only secrets scoped to the account are available to use in Delegate Profiles.
  6. If you want to restrict the use of the secret to specific applications and environments, do the following:
    1. In Usage Scope, click the drop-down under Applications, and click the name of the application.
    2. In Environments, click the name or type of environment.
  7. Click SUBMIT.

Now, when you are in an application entity that uses files, you can reference the encrypted file. For example, in the following Configuration File dialog, click Encrypt File and the File dropdown lets you choose the file you added in Secrets Management:

To use Encrypted Files, you have to add them to a Service. You can then use the Encrypted File in any Workflow that deploys that Service using the variable ${configFile.getAsBase64("fileName")}.

For information on adding Encrypted Files to a Service, see Config Files.

Restricting Secrets Usage

For encrypted texts and files, you have the following restriction options.

Scope to Account

If your Harness User account is part of a User Group with the Administer Other Account Functions permission enabled, you will see the Scope to Account option in the Encrypted Text and File dialogs.

Select Scope to Account to make this encrypted file secret available to Delegate Profile scripts only. Only secrets scoped to the account are available to use in Delegate Profiles.

For more information, see Managing Users and Groups (RBAC) and Delegate Profiles.

Usage Scope

You might want to restrict which Harness User Groups can use a secret. Restrictions are set up using the Usage Scope of the secret and the Application Permissions of the User Group.

For example, in the following image, the Usage Scope of the secret is limited to the ExampleApp Application and the Application Permissions for a User Group are also limited to ExampleApp:

This results in limiting the User Group to using that secret only, assuming no other secrets Usage Scopes include ExampleApp.

Referencing Existing Secrets

If you already have secrets created in HashiCorp Vault, AWS Secrets Manager, or CyberArk Enterprise Password Vault before using it as the Harness Secret Manager, you do not need to recreate the existing secrets in Harness again.

Harness does not query the secret manager for existing secrets, but you can create a secret in Harness that references an existing secret in HashiCorp Vault or AWS Secrets Manager. No new secret is created in those providers. If you delete the secret in Harness, it does not delete the secret in the provider.

Existing Vault Secrets

You can create a Harness secret that refers to the existing Vault secret using a path and key, such as /path/secret_key#my_key.

In the above example, /foo/bar is the pre-existing path, MySecretKey is the secret name, and MyKey is the key used to lookup the secret value.

This Harness secret is simply a reference pointing to an existing Vault secret. Deleting this Harness secret will not delete the Vault secret referred to by this secret.

You can also reference pre-existing Vault secrets in the Harness YAML editor, as described in Encrypted Information in YAML.

Existing AWS Secrets Manager Secrets

You can create a Harness secret that refers to an existing secret in AWS Secrets Manager using the name of the secret, and a prefix if needed. For example, devops/mySecret.

Referencing Secret Keys

In AWS Secret Manager, your secrets are specified as key-value pairs, using a JSON collection:

To reference a specific key in your Harness secret, you simple add the key name following the secret name, like secret_name#key_name. In the above example, the secret is named example4docs. To reference the example1 key, you would enter example4docs#example1.

Existing CyberArk Secrets

Once you have set up CyberArk as the default Harness Secrets Manager, you can reference existing secrets in the Encrypted Text dialog.

To use an existing CyberArk secrets, enter the following fields.

  • Name - Enter a name for the secret so you can reference it in Harness. This is a Harness setting, not a name in CyberArk.
  • Query - Queries the CyberArk secret manager for the secret. For example, the query Safe=Test;Folder=root\OS\Windows;Object=windows1 search for Safe Test, folder root\OS\Windows, and object name windows1. The query is combined with the user credentials provided in the CyberArk Secret Manager setup to create the complete API query.

The query syntax is:

Safe=<safe>;Folder=<folder>;Object=<name>

What Safe, Folder, and Object are named depends on your CyberArk setup. You can see the Safe as the Address field and Object as Username field in the following example, and so the query would be Address=components;Username=svc_account:

We recommend the query includes enough fields to ensure that multiple secrets are not returned. If multiple secrets are returned, the query will fail.

Using Secrets

Once you have created an encrypted text or file secret, you can reference it. The following examples are for secrets created in the Configuration section of a Harness Service:

  • For Encrypted Files, you reference them in the Workflow using the Service with the variable ${configFile.getAsBase64("file_name")}.
  • For Encrypted Text, you reference them in the Workflow using the Service with the variable ${serviceVariable.var_name} .

For Delegate Profiles, if you wanted to add a Helm repo that requires login credentials to every Kubernetes pod running a Harness Kubernetes Delegate, you can create encrypted text in Harness Secrets Management for those credentials, and then use variable names for those credentials in the Delegate Profile using the ${secrets.getValue("secret_name")} expression.

For more information about Delegate Profiles, see Delegate Profiles and Common Delegate Profile Scripts.

When using a secret in a Delegate Profile, ensure that the Usage Scope for the secret is not limited to an Application as the Delegate is an Account-level component. The ${secrets.getValue("secret_name")} expression is primarily for the Delegate Profile script and requires that the secret is Account-level: having no Usage Scope set (not even All Applications). You do this by selecting the Scope to Account option in the secret:

Let’s walk through this example using Delegate Profiles:

  1. In Harness, hover over Continuous Security, and then click Secrets Management.
    The Secrets Management page appears.
  2. Under Execution Credentials, click Encrypted Text. The Encrypted Text page appears.
  3. Click Add Encrypted Text. The Add Encrypted Text dialog appears.
  4. In Name, enter repoUsername. This name will be used later in the Delegate Profile script to reference this secret.
  5. In Usage Scope, click the X next to both All Applications rows, as this secret is scoped to Account-level Delegates.
  6. In Value, enter any username. The dialog will look like this:
  7. Remove all Applications from the Usage Scope. This will scope the secret to the Account-level. It can then be used in a Delegate Profile, or anywhere in your Account.
  8. Click SUBMIT.
  9. Add a second encrypted text with the name repoPassword, using any password. Be sure to delete the Usage Scope settings, also. The dialog will look like this:
  10. Click SUBMIT. Now you can create a Delegate Profile and use these secrets.
  11. Click Setup.
  12. Click Harness Delegates.
  13. Click Manage Delegate Profiles, and then Add Delegate Profile.
    The Manage Delegate Profile dialog appears.
  14. In Name, enter Helm Repo.
  15. In Startup Script, enter your Helm commands using the secrets you created:

    helm init --client-only

    helm repo add --username${secrets.getValue(“repoUsername”)}--password${secrets.getValue(“repoPassword”)}nginx https://charts.bitnami.com/bitnami

    helm repo update

    The secrets are referenced as variables using ${secrets.getValue()} and the names you gave them, repoUsername and repoPassword:

    ${secrets.getValue(“repoUsername”)}
    ${secrets.getValue(“repoPassword”)}

    The Manage Delegate Profile dialog will look like this:
  16. Click SUBMIT.

Now when you add this profile to a Kubernetes Delegate, it will add the Helm repo using the credentials you added as Encrypted Text in Harness Secrets Management.

A quick way to get the name of a secret is to hover over the secrets in Secrets Management and click the copy icon:

Invalid Characters in Secret Names

The following characters are not allowed in the names of secrets:

 ~ ! @ # $ % ^ & * ' " ? / < > , ;

Secrets in Outputs

When a secret is displayed in an output, Harness substitutes the secret value with the secret name so that the secret value is never displayed. For example, here the secret values for repo username and password are replaced with <<<secret_name>>>:

helm repo add --username <<<repoUsername>>> --password <<<repoPassword>>> nginx https://charts.bitnami.com/bitnami

If you accidentally use a very common value in your secret, like whitespace or a single character, the <<<secret_name>>> substitution might appear in multiple places in the output. For example, if your secret value is a and your output is Alfalfa sprouts are great, this would result in output like this:

Alf<<<my_secret>>>lf<<<my_secret>>> sprouts <<<my_secret>>>re gre<<<my_secret>>>t

If you see output similar to this, review your secret and fix the error.


How did we do?