Skip to main content
Version: 17.x (unreleased)

Joining Services via Azure Managed Identity

This guide will explain how to use the Azure join method to configure Teleport instances to join your Teleport cluster without sharing any secrets when they are running in an Azure Virtual Machine.

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

For other methods of joining a Teleport process to a cluster, see Joining Teleport Services to a Cluster.

Prerequisites​

  • A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl admin tool and tsh client tool.

    Visit Installation for instructions on downloading tctl and tsh.

  • An Azure Virtual Machine running Linux with the Teleport binary installed. The Virtual Machine must have a Managed Identity assigned to it with permission to read virtual machine info.
  • To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example: 
    $ tsh login --proxy=teleport.example.com --user=email@example.com
    $ tctl status
    # Cluster  teleport.example.com
    # Version  17.0.0-dev
    # CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
    If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

Step 1/5. Set up a Managed Identity​

Every virtual machine hosting a Teleport process using the Azure method to join your Teleport cluster needs a Managed Identity assigned to it. The identity requires the Microsoft.Compute/virtualMachines/read permission so Teleport can look up the virtual machine. No other permissions are required.

Create a custom role​

Enter the name of your Azure resource group in the Azure Portal search box and visit the page for that resource group. On the left navigation sidebar, click the Access control (IAM) tab. In the row of buttons at the top of the Access control (IAM) panel, click Add > Add custom role.

In the Custom role name field, enter teleport-read-vm.

Click the Permissions tab, then within the Permissions view, click +Add permissions.

Enter Microsoft.Compute/virtualMachines/read in the search box. Click the Microsoft Compute box, then enable Read: Get Virtual Machine. Click Add.

Click Review + create, then Create.

Create an Azure managed identity​

Visit the Managed Identities view in Azure Portal.

Click Create.

Under Subscription, Resource group, and Region, choose the ones that your VM belongs to.

In the Name field, enter teleport-azure.

Click Review + create, then Create.

Once creation finishes, click Go to resource. On the page for the new identity, copy the value for the Client ID so you can use it later in this guide.

Assign the teleport-read-vm role to the teleport-azure identity​

Enter the name of your Azure resource group in the Azure Portal search box and visit the page for that resource group. On the left navigation sidebar, click the Access control (IAM) tab. In the row of buttons at the top of the Access control (IAM) panel, click Add > Add role assignment.

Within the Add role assignment screen, click teleport-read-vm.

Scroll to the bottom of the screen and click Next.

Within the Members tab, in the Assign access to field, choose Managed identity. Click Select members.

On the right sidebar, find the Managed identity dropdown menu and select User-assigned managed identity. Choose the teleport-azure identity you created earlier.

Click Select, then Review + assign.

Verify that your Role is teleport-read-vm, the Scope matches your chosen resource group, and the Members field includes the teleport-azure managed identity you created earlier.

Click Review + assign again.

Attach an identity to your Azure VM​

In the Virtual machines view of Azure Portal, click on the name of the VM you are using to host the Teleport Service.

On the right side panel, click the Security/Identity tab, then within the Identity view, click the User assigned tab. Click +Add, then select the teleport-azure identity. Click Add.

Navigate back to Identity tab in the page for your Azure VM. You should see the new identity listed in the User assigned sub-tab:

IMPORTANT

As part of authentication, Teleport will be able to do anything allowed by the identity. If you use a managed identity other than the one created in this guide, we strongly recommend limiting its permissions and scope.

Step 2/5. Create the Azure joining token​

Under the hood, Teleport processes will prove that they are running in your Azure subscription by sending a signed attested data document and access token to the Teleport Auth Service. The VM's identity must match an allow rule configured in your Azure joining token.

Create the following token.yaml with an allow rule specifying your Azure subscription and the resource group that your VM's identity must match.

# token.yaml
kind: token
version: v2
metadata:
  # the token name is not a secret because instances must prove that they are
  # running in your Azure subscription to use this token
  name: azure-token
spec:
  # use the minimal set of roles required
  roles: [Node]
  join_method: azure
  azure:
    allow:
      # specify the Azure subscription which Teleport processes may join from
      - subscription: 11111111-1111-1111-1111-111111111111
      # multiple allow rules are supported
      - subscription: 22222222-2222-2222-2222-222222222222
      # resource_groups is optional and allows you to restrict the resource group of
      # joining Teleport processes
      - subscription: 33333333-3333-3333-3333-333333333333
        resource_groups: ["group1", "group2"]

The token name azure-token is just an example and can be any value you want to use, as long as you use the same value for join_params.token_name in Step 3.

Run the following command to create the token:

$ tctl create -f token.yaml

Step 3/5 Install Teleport​

Install Teleport on your Azure Linux VM.

Install Teleport on your Linux server:

  1. Assign edition to one of the following, depending on your Teleport edition:

    EditionValue
    Teleport Enterprise Cloudcloud
    Teleport Enterprise (Self-Hosted)enterprise
    Teleport Community Editionoss

  2. Get the version of Teleport to install. If you have automatic agent updates enabled in your cluster, query the latest Teleport version that is compatible with the updater:

    $ TELEPORT_DOMAIN=example.teleport.com
    $ TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/automaticupgrades/channel/default/version | sed 's/v//')"

    Otherwise, get the version of your Teleport cluster:

    $ TELEPORT_DOMAIN=example.teleport.com
    $ TELEPORT_VERSION="$(curl https://$TELEPORT_DOMAIN/v1/webapi/ping | jq -r '.server_version')"

  3. Install Teleport on your Linux server:

    $ curl https://cdn.teleport.dev/install-v15.4.11.sh | bash -s ${TELEPORT_VERSION} edition

    The installation script detects the package manager on your Linux server and uses it to install Teleport binaries. To customize your installation, learn about the Teleport package repositories in the installation guide.

Step 4/5. Configure your Teleport process​

The Azure join method can be used for Teleport processes running the SSH, Proxy, Kubernetes, Application, Database, or Desktop Service.

Configure your Teleport process with a custom teleport.yaml file. Use the join_params section with token_name matching your token created in Step 2 and method: azure as shown in the following example config:

# /etc/teleport.yaml
version: v3
teleport:
  join_params:
    token_name: azure-token
    method: azure
    azure:
      # client_id is the client ID of the managed identity created in Step 1.
      client_id: 11111111-1111-1111-1111-111111111111
  proxy_server: teleport.example.com:443
ssh_service:
  enabled: yes
auth_service:
  enabled: no
proxy_service:
  enabled: no

Step 5/5. Launch your Teleport process​

Start Teleport on the Azure VM.

Configure your Teleport instance to start automatically when the host boots up by creating a systemd service for it. The instructions depend on how you installed your Teleport instance.

On the host where you will run your Teleport instance, enable and start Teleport:

$ sudo systemctl enable teleport
$ sudo systemctl start teleport

You can check the status of your Teleport instance with systemctl status teleport and view its logs with journalctl -fu teleport.

Confirm that your Teleport process is able to connect to and join your cluster. You're all set!