Encrypting your Concourse deployment is a good first step to securing your CI/CD tools. For even greater security, VMware recommends that you use a credential manager as well.
Explicit credential management provides temporary credentials to your Concourse builds. These credentials are not stored anywhere. Credential management also allows for credentials to be rotated and managed from outside the pipeline or team, and prevents them from being revealed by the get-pipeline command. For more information about get-pipeline, see the Concourse documentation.
Credential management works by replacing the credentials with parameters in your pipeline or task config files. For more information, see the Concourse documentation. When the ATC is about to run the step or check that is configured with the parameters, it resolves them by fetching the values from the credential manager. This ensures that credentials are not transmitted over insecure channels, or stored in build history.
Concourse supports CredHub and Vault for external credential management. For the full list of supported external credential managers, see the Concourse documentation.
Storing Credentials
You can use a credential manager to control the following resources:
- Source under resources resource types in a pipeline
- Tasks in their entirety: whether from file or config in a pipeline or from a config executed with fly execute
- webhook_token under resources in a pipeline
Where these values are looked up and how the credential manager is configured depends on whether you use CredHub or Vault. See Use CredHub or Use Vault below.
Use CredHub
This section describes using CredHub for credential management in Concourse. For general information, see the CredHub repository.
CredHub Configuration
The web node is statically configured with a CredHub server URL with TLS and client config.
To configure CredHub, provide the credhub properties to your web node. For information about this process, see credhub in the BOSH documentation. For additional information, see The CredHub credential manager in the Concourse documentation.
CredHub Credential Lookup Rules
When resolving a parameter such as ((foo-param)), it looks in the following paths, in order:
/concourse/TEAM-NAME/PIPELINE-NAME/FOO-PARAM/concourse/TEAM-NAME/FOO-PARAM
The leading /concourse can be changed by specifying --credhub-path-prefix.
CredHub credentials have different types, which can contain multiple values. For example, the user type specifies both username and password. You can specify the field to grab through . syntax, such as ((foo-param.username)).
If the web node is interpolating a variable to schedule some work that is scoped to a pipeline, it first looks in the path of that pipeline. If it is not found there, it looks in the team path. This allows credentials to be scoped widely if they are common across many pipelines.
If the web node is interpolating a variable to run a one-off build, it only looks in the path for the team that the user is currently logged in to.
Use Vault
This section describes using HashiCorp Vault for credential management in Concourse. For general information, see the Vault homepage.
Vault Configuration
The web node is statically configured with a Vault server URL (plus any TLS config) and either a client token or an authentication backend.
To configure Vault, provide the vault properties to your web node. For information about this process, see vault in the BOSH documentation. For additional information, see The Vault credential manager in the Concourse documentation.
Vault Credential Lookup Rules
When resolving a parameter such as ((YOUR-PARAM)), the web node looks in the following paths:
/concourse/TEAM-NAME/PIPELINE-NAME/YOUR-PARAM/concourse/TEAM-NAME/YOUR-PARAM
The leading /concourse can be changed by specifying --vault-path-prefix.
If the web node is interpolating a variable to schedule some work that is scoped to a pipeline, it first looks in the path of that pipeline. If it is not found there, it looks in the team path. This allows credentials to be scoped widely if they are common across many pipelines.
If the web node is interpolating a variable to run a one-off build, it only looks in the path for the team that the user is currently logged in to.
