Using MachineID to Generate Join Tokens

[corkrean]

This article will detail how to use Teleport MachineID to generate join tokens for CICD systems. After you've completed this guide, you will always have a valid token (/var/lib/teleport/join_token) that can be used by your CICD system to join resources to a Teleport cluster.

If you're an AWS user, you should consider IAM joining instead of the method described here.

1. Create a Teleport role for your bot user

Populate a file with the following then run the tctl create -f example.yaml command.

kind: role
metadata:
  id: 1660166744961925023
  name: token-role
spec:
  allow:
    rules:
    - resources:
      - token
      verbs:
      - create

2. Configure MachineID

• On the auth server, create the bot: tctl bots add token-generator --roles=token-role
• On the server hosting the MachineID bot, create the MachineID configuration file at /etc/tbot.yaml:

onboarding:
  token: <insert token here>
  ca_pins:
  - <insert ca pin here>
  join_method: token
storage:
  directory:
    path: /var/lib/teleport/bot
    symlinks: secure
    acls: try
destinations:
    - directory:      
          path: /opt/machine-id
          symlinks: try-secure
          acls: try
debug: false
auth_server: proxy.example:443 #you can also do auth.example.com:3025 to connect to the auth server
certificate_ttl: 1h0m0s
renewal_interval: 20m0s
oneshot: false

• Setup the SystemD unit file for the bot (/etc/systemd/system/tbot.service):

[Unit]
Description=tbot service
After=network.target

[Service]
Type=simple
Restart=on-failure
ExecStart=/usr/local/bin/tbot start --config=/etc/tbot.yaml
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/run/tbot.pid

[Install]
WantedBy=multi-user.target/etc/

• Start the bot systemctl daemon-reload ; systemctl enable tbot.service ; systemctl start tbot.service

3. Create a join token generation script

Recommended location is /usr/local/bin/token-generator.sh

#!/bin/bash

#You will need to edit the --type flag depending on what resource(s) you are trying to join to Teleport

/usr/local/bin/tctl tokens add --type=kube --ttl=3h -i /opt/machine-id/identity | head -n 1 | sed 's/.*: //' | sed 's/.$//' > /var/lib/teleport/join_token

4. Configure SystemD timer and service for the MachineID bot

For most configurations, these files should be stored in /etc/systemd/system.

token.timer:

[Unit]
Description=Timer generating a join token

[Timer]
OnCalendar=hourly
Persistent=true

[Install]
WantedBy=timers.target
root@ip-10-0-0-221:/etc/systemd/system#

token.service:

[Unit]
Description=Timer generating a join token

[Timer]
OnCalendar=hourly
Persistent=true

[Install]
WantedBy=timers.target
root@ip-10-0-0-221:/etc/systemd/system# cat token.service
[Unit]
Description=Service invoking the script that generates a join token.

[Service]
Type=oneshot
ExecStart=/usr/local/bin/token-generator.sh

5. CICD setup

Configure your CICD tooling to use the join token that is stored at /var/lib/teleport/join_token to add resources to your Teleport cluster.

[bearrito]

This is useful, however the tbot.yaml file isn't quite correct. The token headings need to be under "onboarding" https://goteleport.com/docs/machine-id/reference/configuration/

Something like

onboarding: 
  ca_pins: 
    - "sha256:..."
  join_method: iam
  token: your-token-name

[corkrean]

Yes, good catch. I have updated the post.

[bearrito]

Another small nit, I believe you have to include the auth-server as a param when using identity file.

https://goteleport.com/docs/reference/cli/#on-a-remote-host-with-an-identity-file

When using the --identity flag, the user must provide the --auth-server flag with the address of an Auth Service or Proxy Service so tctl knows which cluster to authenticate to.