Skip to content

Commit 432231e

Browse files
timothyb89timothyb89
authored
[v17] Machine ID: Documentation for Bitbucket Pipelines joining (#49387)
* 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
1 parent 773cabc commit 432231e

File tree

4 files changed

+223
-2
lines changed

4 files changed

+223
-2
lines changed

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

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
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/4. 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/4. Create the Machine ID bot
42+
43+
(!docs/pages/includes/machine-id/create-a-bot.mdx!)
44+
45+
## Step 3/4. 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/4. 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+
This example workflow defines a "custom" pipeline that can be triggered manually
108+
from "Pipelines" or "Branches" views:
109+
110+
```yaml
111+
image: atlassian/default-image:3
112+
113+
pipelines:
114+
custom:
115+
run-tbot:
116+
- step:
117+
oidc: true
118+
script:
119+
# Download and extract Teleport
120+
- wget https://cdn.teleport.dev/teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
121+
- tar -xvf teleport-v(=teleport.version=)-linux-amd64-bin.tar.gz
122+
123+
# Run `tbot` in identity mode for SSH access
124+
- ./teleport/tbot start identity --destination=./tbot-user --join-method=bitbucket --proxy-server=example.teleport.sh:443 --token=bot-bitbucket --oneshot
125+
126+
# Make use of the generated SSH credentials
127+
- ssh -F ./tbot-user/ssh_config user@node.example.teleport.sh echo "hello world"
128+
```
129+
130+
This example will start `tbot` in identity mode to generate SSH credentials.
131+
Refer to the [`tbot start` documentation](../../../reference/cli/tbot.mdx#tbot-start)
132+
for details on using other modes such as database, application, and Kubernetes
133+
access.
134+
135+
If you're adapting an existing workflow, note these steps:
136+
1. Set `oidc: true` on the step properties so that step will be issued a token
137+
1. Download and extract a `.tar.gz` Teleport build
138+
1. Run `tbot` with `--join-method=bitbucket`, `--token=example-bot` (or
139+
whichever name was configured in Step 3), and `--oneshot`
140+
141+
<Admonition type="warning" title="Sharing credentials between steps">
142+
Note that in Bitbucket Pipelines, outputs cannot be securely shared between
143+
steps as anything stored using `artifacts` will remain downloadable once the CI
144+
run has completed.
145+
146+
Due to this limitation, all operations making use of Teleport credentials should
147+
be performed as part of the same step. If necessary, you can duplicate the
148+
script shown here to download and run `tbot` multiple times in a given run if
149+
credentials are needed in multiple steps.
150+
</Admonition>
151+
152+
## Further steps
153+
154+
- Follow the [access guides](../access-guides/access-guides.mdx) to finish configuring `tbot` for
155+
your environment.
156+
- Read the [configuration reference](../../../reference/machine-id/configuration.mdx) to explore
157+
all the available configuration options.
158+
- For more information about Bitbucket Pipelines itself, read
159+
[their documentation](https://support.atlassian.com/bitbucket-cloud/docs/get-started-with-bitbucket-pipelines/).
160+

‎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)