Credential Management in Concourse

Encrypting your Concourse deployment is a good first step to securing your CI/CD tools. For even greater security, Pivotal 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 get-pipeline.

Credential management works by replacing the credentials with ((parameters)) in your pipeline or task config files. When the ATC is about to run the step or check that is configured with the parameters, it will resolve 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.

What credentials can I store?

You can use a credential manager to control the following resources:

Where these values are looked up and how the credential manager is configured depends on the backend. Consult the relevant section below for whichever backend you want to use.

Using CredHub

Configuration

The ATC is statically configured with a Credhub server URL with TLS and client config.

For example, to point the ATC at an internal Credhub server with TLS signed by a local CA, using client id and secret, you may configure:

concourse web ... \
  --credhub-url https://10.2.0.3:9000 \
  --credhub-ca-cert /etc/my-ca.cert \
  --credhub-client-id =db02de05-fa39-4855-059b-67221c5c2f63 \
  --credhub-client-secret 6a174c20-f6de-a53c-74d2-6018fcceff64

Credential Lookup Rules

When resolving a parameter such as ((foo_param)), it will look 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 actually have different types, which may contain multiple values. For example, the user type specifies both username and password. You can specified the field to grab via . syntax, e.g. ((foo_param.username))

If the action is being run in the context of a pipeline (e.g. a check or a step in a build of a job), the ATC will first look in the pipeline path. If it’s not found there, it will look in the team path. This allows credentials to be scoped widely if they’re common across many pipelines.

If an action is being run in a one-off build, the ATC will only look in the team path.

Using Vault

Configuration

The ATC is statically configured with a Vault server URL (plus any TLS config), and either a client token or an auth backend.

To configure Vault, provide the vault properties to your ATC. More details on this process are described in the BOSH documentation. Additional details can be found on the Concourse documentation regarding Using Vault

Credential Lookup Rules

When resolving a parameter such as ((YOUR_PARAM)), the ATC looks in the following paths:

  • /concourse/TEAM_NAME/PIPELINE_NAME/YOUR_PARAM
  • /concourse/TEAM_NAME/YOUR_PARAM

If you need to, change the leading /concourse by specifying --vault-path-prefix.

If the action runs in the context of a pipeline, the ATC looks in the pipeline path first. If the action is not found there, the ATC looks in the team path. This allows credentials to be scoped widely if they are common across many pipelines.

If an action is run in a one-off build, the ATC only looks in the team path.

Create a pull request or raise an issue on the source for this page in GitHub