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

Joining Services via Azure Managed Identity

Report an IssueView as Markdown

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.

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

How it works​

Under the hood, Teleport processes 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.

Prerequisites​

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

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

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

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

  • An Azure Virtual Machine running Linux with the Teleport binary installed. The Virtual Machine must have a Managed Identity assigned to it.

  • Your network must allow the Azure Virtual Machine to access child paths at the following endpoint in order to fetch a certificate authority that the Auth Service can use to authenticate it as an Azure VM in the correct account:

    http://www.microsoft.com/pkiops/certs/

  • For self-hosted users, your network must allow the Teleport Auth Service to access the following endpoints in order to verify signed documents sent by the Teleport Agent:

    EndpointResource at the endpoint
    https://sts.windows.net/ and child pathsOIDC discovery document, required for requesting keys for verifying the JSON web token sent by the Teleport Agent
    https://login.microsoftonline.com/common/discovery/keysPublic keys used to verify the signature of a JSON web token sent by the Teleport Agent
    https://management.azure.com/Data about the VM's subscription ID and resource group. Retrieved if the Auth Service cannot extract a VM resource ID from the JWT sent by the Teleport Agent.

  • One of the following client tools for managing Teleport resources:

Step 1/3. 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.

To set up a Managed Identity:

  1. Navigate to Virtual machines view if you're hosting Teleport on an Azure VM, or navigate to Virtual machine scale sets view if you're hosting Teleport on an Azure VMSS.
  2. Select the VM or VMSS hosting your Teleport Service.
  3. In the right-side panel, click the Security/Identity tab.
  4. Under the Identity section, select the System assigned tab.
  5. Toggle the Status switch to On.
  6. Click Save.

If you're using VMSS and it is configured with manual upgrade mode, you must update the VM instances for the identity changes to take effect:

  • Click the Instances tab in the right panel.
  • Select the VM instances to update.
  • Click Restart.

Step 2/3. Create the 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. You can create the token with tctl as well as the Teleport Terraform provider or Kubernetes operator.

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.

# 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"]

Run the following command to create the token:

tctl create -f token.yaml

Step 3/3. Set up Teleport on your Azure Linux VM​

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

  1. Install Teleport on your Azure Linux VM.

    To install Teleport binaries on your Linux server, the recommended installation method is the cluster install script. It will select the correct version, edition, and installation mode for your cluster.

    1. Assign teleport.example.com:443 to your Teleport cluster hostname and port, but not the scheme (https://).

    2. Run your cluster's install script:

      curl "https://teleport.example.com:443/scripts/install.sh" | sudo bash

  2. 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 a user-assigned managed identity.
      # Omit this value when using a system-assigned managed identity.
      client_id: 11111111-1111-1111-1111-111111111111
  proxy_server: teleport.example.com:443
ssh_service:
  enabled: true
auth_service:
  enabled: false
proxy_service:
  enabled: false

  3. 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.

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

Troubleshooting​

If you have followed the steps in this guide and your Teleport Agent cannot join the cluster, check the logs of the Teleport Agent and, for self-hosted clusters, the Teleport Auth Service. Look for any of the following messages.

fetching intermediate certificate​

Your Teleport Agent logs may include a message similar to the following:

level=ERROR msg="Failed to establish connection to cluster." identity=Node
error="getting intermediate CA for attested data: fetching intermediate certificate:
Get \"http://www.microsoft.com/pkiops/certs/Microsoft%20Azure%20RSA%20TLS%20Issuing%20CA%2004%20-%20xsign.crt\":
context deadline exceeded (Client.Timeout exceeded while awaiting headers)"

If you see this message, make sure your network allows the Teleport Agent to reach child paths of the following endpoint:

http://www.microsoft.com/pkiops/certs/

The agent fetches a CA used to sign Microsoft Instance Metadata Service data documents and includes it in a request to the Teleport Auth Service, which also includes a signed IMDS document containing information about the Azure VM. The Auth Service uses the CA to verify the document.

checking Azure challenge solution​

If you are a self-hosted Teleport user and your Teleport Agent cannot join the cluster, check the Teleport Auth Service logs for the following:

level=WARN msg="Failure to join cluster occurred"
error="checking Azure challenge solution: ..."
remote_addr="10.0.0.5:54321" token_name="my-token" token_join_method="azure"

In this case, the Auth Service has encountered an issue verifying one of the following signed documents sent by the Teleport Agent:

  • An IMDS message containing the Azure subscription ID and VM ID
  • A JSON web token containing the VM's managed identity and resource ID

Make sure the Teleport Auth Service can reach the URLs listed in the Prerequisites.