Skip to content

Commit 039e762

Browse files
timothyb89timothyb89
authored
[v16] Machine ID: Documentation for Bitbucket Pipelines joining (#49386)
* Machine ID: Documentation for Bitbucket Pipelines joining This adds guides and other documentation for the `bitbucket` join method, which allows Machine ID bots to join from Bitbucket Pipelines runs without shared secrets. Follow up to #48724 * Linter appeasement (round 1) * Add note about braces in UUIDs * Adjust steps for v16 without new CLI features * Linter appeasement * Remove reference to a specific identity output type
1 parent 9ed545e commit 039e762

File tree

4 files changed

+250
-2
lines changed

4 files changed

+250
-2
lines changed

‎docs/pages/enroll-resources/machine-id/deployment/bitbucket.mdx

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
title: Deploying Machine ID on Bitbucket Pipelines
3+
description: How to install and configure Machine ID on Bitbucket Pipelines
4+
---
5+
6+
In this guide, you will configure Machine ID's agent, `tbot`, to run within a
7+
Bitbucket Pipelines workflow. The bot will be configured to use the `bitbucket`
8+
delegated joining method to eliminate the need for long-lived secrets.
9+
10+
## How it works
11+
12+
The `bitbucket` join method is a secure way for Machine ID bots to authenticate
13+
with the Teleport Auth Service without using any shared secrets. Instead, it
14+
makes use of an OpenID Connect token that Bitbucket Pipelines injects into the
15+
job environment.
16+
17+
This token is sent to the Teleport Auth Service, and assuming it has been
18+
configured to trust Bitbucket's identity provider and all identity assertions
19+
match, the authentication attempt will succeed.
20+
21+
## Prerequisites
22+
23+
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
24+
25+
- (!docs/pages/includes/tctl.mdx!)
26+
- A Bitbucket repository you can push to.
27+
28+
## Step 1/5. Determine Bitbucket configuration
29+
30+
Bitbucket joining requires a number of configuration parameters that can be
31+
found in your repository settings. From the Bitbucket repository, navigate to
32+
"Repository settings", then in the sidebar under "Pipelines" select "OpenID
33+
Connect".
34+
35+
From this page, note the following values:
36+
- Identity provider URL (<Var name="identity-provider-url" />)
37+
- Audience (<Var name="audience" />)
38+
- Workspace UUID, including the braces (<Var name="workspace-uuid" />)
39+
- Repository UUID, including the braces (<Var name="repository-uuid" />)
40+
41+
## Step 2/5. Create the Machine ID bot
42+
43+
(!docs/pages/includes/machine-id/create-a-bot.mdx!)
44+
45+
## Step 3/5. Create the join token for Bitbucket Pipelines
46+
47+
In order to allow your Pipelines workflow to authenticate with your Teleport
48+
cluster, you'll first need to create a join token. These tokens set out criteria
49+
by which the Auth Service decides whether or not to allow a bot or node to join.
50+
51+
Create a file named `bot-token.yaml`, ensuring that you replace the
52+
`identity_provider_url`, `audience`, `workspace_uuid`, and `repository_uuid`
53+
with the values from Step 1.
54+
55+
```yaml
56+
kind: token
57+
version: v2
58+
metadata:
59+
name: example-bot
60+
spec:
61+
roles: [Bot]
62+
join_method: bitbucket
63+
bot_name: example
64+
bitbucket:
65+
identity_provider_url: <Var name="identity-provider-url" />
66+
audience: <Var name="audience" />
67+
# allow specifies the rules by which the Auth Service determines if `tbot`
68+
# should be allowed to join.
69+
allow:
70+
- workspace_uuid: <Var name="workspace-uuid" />
71+
repository_uuid: <Var name="repository-uuid" />
72+
```
73+
74+
Let's go over the token resource's fields in more detail:
75+
76+
- `metadata.name` defines the name of the token. Note that this value will need
77+
to be used in other parts of the configuration later.
78+
- `spec.bot_name` is the name of the Machine ID bot that this token will grant
79+
access to. Note that this value will need to be used in other parts of the
80+
configuration later.
81+
- `spec.roles` defines which roles that this token will grant access to. The
82+
value of `[Bot]` states that this token grants access to a Machine ID bot.
83+
- `spec.join_method` defines the join method the token is applicable for. Since
84+
this guide only focuses on Bitbucket Pipelines, you will set this to to
85+
`bitbucket`.
86+
- `spec.bitbucket.identity_provider_url` is the identity provider URL shown in
87+
the Bitbucket repository settings, under Pipelines and OpenID Connect.
88+
- `spec.bitbucket.audience` is the audience value shown in the Bitbucket
89+
repository settings, under Pipelines and OpenID connect.
90+
- `spec.bitbucket.allow` is used to set rules for what Bitbucket Pipelines runs
91+
will be able to authenticate by using the token.
92+
93+
Refer to the [token reference](../../../reference/join-methods.mdx#bitbucket-pipelines-bitbucket)
94+
for a full list of valid fields.
95+
96+
Apply this to your Teleport cluster using `tctl`:
97+
98+
```code
99+
$ tctl create -f bot-token.yaml
100+
```
101+
102+
## Step 4/5. Configure a Bitbucket Pipelines workflow
103+
104+
With the bot and join token created, you can now configure a workflow that can
105+
authenticate to Teleport.
106+
107+
To configure `tbot`, a YAML file will be used. In this example we'll store this
108+
within the repository itself, but this could be generated or created by the
109+
CI pipeline itself.
110+
111+
Create `tbot.yaml` within your repository:
112+
113+
```yaml
114+
version: v2
115+
proxy_server: example.teleport.sh:443
116+
onboarding:
117+
join_method: bitbucket
118+
token: example-bot
119+
oneshot: true
120+
storage:
121+
type: memory
122+
# outputs will be filled in during the completion of an access guide.
123+
outputs: []
124+
```
125+
126+
Replace:
127+
128+
- `example.teleport.sh:443` with the address of your Teleport Proxy. If
129+
connecting directly to an Auth Service, replace `proxy_server:` with
130+
`auth_server:`.
131+
- `example-bot` with the name of the token you created in the second step
132+
133+
Next, define a Pipelines workflow that downloads the `tbot` binary and starts
134+
it using the `tbot.yaml` configured above. This example workflow defines
135+
a "custom" pipeline that can be triggered manually from "Pipelines" or
136+
"Branches" views, but any type of workflow may be used:
137+
138+
```yaml
139+
image: atlassian/default-image:3
140+
141+
pipelines:
142+
custom:
143+
run-tbot:
144+
- step:
145+
oidc: true
146+
script:
147+
# Download and extract Teleport
148+
- wget https://cdn.teleport.dev/teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
149+
- tar -xvf teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
150+
151+
# Run `tbot` in identity mode for SSH access
152+
- ./teleport/tbot start -c tbot.yaml
153+
```
154+
155+
Once run, tbot will start and authenticate to Teleport. Note that at this point,
156+
no outputs will have been configured so it will not yet have credentials to
157+
connect to any resources.
158+
159+
If you're adapting an existing workflow, note these steps:
160+
1. Set `oidc: true` on the step properties so that step will be issued a token
161+
1. Download and extract a `.tar.gz` Teleport build
162+
1. Run `tbot start -c tbot.yaml` with the configuration file defined above
163+
164+
<Admonition type="warning" title="Sharing credentials between steps">
165+
Note that in Bitbucket Pipelines, outputs cannot be securely shared between
166+
steps as anything stored using `artifacts` will remain downloadable once the CI
167+
run has completed.
168+
169+
Due to this limitation, all operations making use of Teleport credentials should
170+
be performed as part of the same step. If necessary, you can duplicate the
171+
script shown here to download and run `tbot` multiple times in a given run if
172+
credentials are needed in multiple steps.
173+
</Admonition>
174+
175+
## Step 5/5. Configure outputs
176+
177+
(!docs/pages/includes/machine-id/configure-outputs.mdx!)
178+
179+
## Further steps
180+
181+
- Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
182+
your environment.
183+
- Read the [configuration reference](../../../reference/machine-id/configuration.mdx) to explore
184+
all the available configuration options.
185+
- For more information about Bitbucket Pipelines itself, read
186+
[their documentation](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/).
187+

‎docs/pages/enroll-resources/machine-id/deployment/deployment.mdx

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,9 +68,10 @@ integration and continuous deployment platform
6868

6969
| Platform | Installation method | Join method |
7070
|-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------|------------------------------------|
71+
| [Bitbucket Pipelines](bitbucket.mdx) | TAR archive | Bitbucket-signed identity document |
7172
| [CircleCI](circleci.mdx) | TAR archive | CircleCI-signed identity document |
7273
| [GitLab](gitlab.mdx) | TAR archive | GitLab-signed identity document |
7374
| [GitHub Actions](github-actions.mdx) | Teleport job available through the GitHub Actions marketplace | GitHub-signed identity document. |
7475
| [Jenkins](jenkins.mdx) | Package manager or TAR archive | Static join token |
7576
| [Spacelift](../../../admin-guides/infrastructure-as-code/terraform-provider/spacelift.mdx) | Docker Image | Spacelift-signed identity document |
76-
| [Terraform Cloud](../../../admin-guides/infrastructure-as-code/terraform-provider/terraform-cloud.mdx) | Teleport Terraform Provider via Teleport's Terraform Registry | Terraform Cloud-signed identity document |
77+
| [Terraform Cloud](../../../admin-guides/infrastructure-as-code/terraform-provider/terraform-cloud.mdx) | Teleport Terraform Provider via Teleport's Terraform Registry | Terraform Cloud-signed identity document |

‎docs/pages/includes/provision-token/bitbucket-spec.mdx

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
```yaml
2+
kind: token
3+
version: v2
4+
metadata:
5+
name: example-bot
6+
spec:
7+
roles: [Bot]
8+
join_method: bitbucket
9+
bot_name: example
10+
bitbucket:
11+
# The URL of the workspace-specific OIDC identity provider. This can be
12+
# found in the repository settings under "Pipelines" and "OpenID Connect".
13+
identity_provider_url: $IDENTITY_PROVIDER_URL
14+
15+
# The audience of the OIDC tokens issued by Bitbucket. This can be found in
16+
# the repository settings under "Pipelines" and "OpenID Connect".
17+
audience: $AUDIENCE
18+
19+
# allow specifies the rules by which the Auth Server determines if `tbot`
20+
# should be allowed to join. All parameters in a given allow entry must
21+
# match for the join attempt to succeed, but many allow rules may be
22+
# provided. One or both of `workspace_uuid` and `repository_uuid` are
23+
# required; all other fields are optional.
24+
allow:
25+
- # The UUID of a workspace whose runs should be allowed to connect. This
26+
# value can be found in the repository settings under "Pipelines" and
27+
# "OpenID Connect". It must be enclosed in braces, i.e. `{...}`. At
28+
# least `workspace_uuid` or `repository_uuid` must be provided.
29+
workspace_uuid: '{WORKSPACE_UUID}'
30+
31+
# The UUID of a repository whose runs should be allowed to connect. This
32+
# value can be found in the repository settings under "Pipelines" and
33+
# "OpenID Connect". It must be enclosed in braces, i.e. `{...}`. At
34+
# least `workspace_uuid` or `repository_uuid` must be provided.
35+
repository_uuid: '{REPOSITORY_UUID}'
36+
37+
# If set, only steps tagged with the deployment environment linked to
38+
# this UUID will be allowed to connect. This value can be found in the
39+
# repository settings under "Pipelines" and "OpenID Connect" when a
40+
# deployment environment is selected from the drop-down menu. It must be
41+
# enclosed in braces, i.e. `{...}`. Optional.
42+
deployment_environment_uuid: '{DEPLOYMENT_ENVIRONMENT_UUID}'
43+
44+
# If set, only workflows running on the named branch will be allowed to
45+
# connect. Optional.
46+
branch_name: "main"
47+
```

‎docs/pages/reference/join-methods.mdx

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -300,7 +300,7 @@ method](#aws-iam-role-iam) or [ephemeral secret tokens](#ephemeral-tokens).
300300

301301
### Azure managed identity: `azure`
302302

303-
The Azure join method is available to any Teleport process running in an
303+
The Azure join method is available to any Teleport process running in an
304304
Azure Virtual Machine. Support for joining a cluster with the Proxy Service
305305
behind a layer 7 load balancer or reverse proxy is available in Teleport 13.0+.
306306

@@ -439,3 +439,16 @@ Support for self-hosted Terraform Enterprise requires Teleport Enterprise.
439439
<Admonition type="note" title="See Also">
440440
- [Run the Teleport Terraform Provider on Terraform Cloud](../admin-guides/infrastructure-as-code/terraform-provider/terraform-cloud.mdx)
441441
</Admonition>
442+
443+
### Bitbucket Pipelines: `bitbucket`
444+
445+
This join method is used to authenticate using Bitbucket's support for OpenID
446+
Connect, and is typically used to allow either Machine ID's `tbot` or the
447+
Teleport Terraform provider to authenticate to Teleport without use of shared
448+
secrets.
449+
450+
(!docs/pages/includes/provision-token/bitbucket-spec.mdx!)
451+
452+
<Admonition type="note" title="See Also">
453+
- [Deploying Machine ID on Bitbucket Pipelines](../enroll-resources/machine-id/deployment/bitbucket.mdx)
454+
</Admonition>

0 commit comments

Comments
 (0)