forked from pivotal-cf/docs-concourse-olm
-
Notifications
You must be signed in to change notification settings - Fork 0
/
credential-management.html.md.erb
84 lines (59 loc) · 5.3 KB
/
credential-management.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
---
title: Credential Management in Concourse
owner: Concourse
---
[Encrypting](./encryption.html) 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](https://concourse-ci.org/fly-get-pipeline.html).
Credential management works by replacing the credentials with [((parameters))](https://concourse-ci.org/fly-set-pipeline.html#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.
For the full list of supported external credential managers,
see [Credential Management](https://concourse-ci.org/creds.html) in the Concourse documentation.
## <a id="what-creds"></a> What credentials can I store?
You can use a credential manager to control the following resources:
<ul>
<li><a href="https://concourse-ci.org/resource-types.html#resource-type-source">Source</a> under <a href="https://concourse-ci.org/resources.html">resources</a> or <a href="https://concourse-ci.org/resource-types.html">resource types</a> in a pipeline</li>
<li><a href="https://concourse-ci.org/resource-types.html#resource-type-source">Source</a> under <a href="https://concourse-ci.org/tasks.html#image_resource">image_resource</a> in a task config</li>
<li><a href="https://concourse-ci.org/task-step.html#task-step-params">Parameters</a> in a pipeline</li>
<li><a href="https://concourse-ci.org/running-tasks.html#providing-values-for-params">Parameters</a> in a task config</li>
</ul>
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.
## <a id="use-credhub"></a> Using CredHub
This section describes using CredHub for credential management in Concourse. For general information, see the [CredHub](https://github.com/cloudfoundry-incubator/credhub) repository.
### <a id="config-credhub"></a> 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
```
### <a id="lookup-rules-credhub"></a> 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.
## <a id="use-vault"></a> Using Vault
This section describes using HashiCorp Vault for credential management in Concourse. For general information, see the [Vault](https://vaultproject.io/) homepage.
### <a id="confi-vault"></a> 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](http://bosh.io/jobs/atc?source=github.com/concourse/concourse&version=3.3.2#p=vault).
Additional details can be found on the Concourse documentation regarding <a href="https://concourse-ci.org/creds.html#vault">Using Vault</a>.
</pre>
### <a id="lookup-rules-vault"></a> Credential Lookup Rules
When resolving a parameter such as ((YOUR\_PARAM)), the ATC looks in the following paths:
<ul>
<li><code>/concourse/TEAM\_NAME/PIPELINE\_NAME/YOUR\_PARAM</code></li>
<li><code>/concourse/TEAM\_NAME/YOUR\_PARAM</code></li>
</ul>
If you need to, change the leading `/concourse` by specifying <code>--vault-path-prefix</code>.
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.