# Join Services with Oracle Cloud This guide will explain how to use the **Oracle join method** to configure Teleport processes to join your Teleport cluster without sharing any secrets when they are running in an Oracle Cloud Infrastructure (OCI) Compute instance. ## How it works The Oracle join method is available to any Teleport process running on an OCI Compute instance. Under the hood, services prove that they are running in your OCI tenant by sending a presigned self-authentication request to the OCI API for the Auth Service to execute. ## Prerequisites - A running Teleport (v17.3.0 or higher) cluster. If you want to get started with Teleport, [sign up](https://goteleport.com/signup) for a free trial or [set up a demo environment](https://goteleport.com/docs/ver/17.x/get-started/deploy-community.md). - 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: **Mac** 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. --- **Windows - Powershell** ``` $ curl.exe -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-windows-amd64-bin.zip Unzip the archive and move the `tctl` and `tsh` clients to your %PATH% NOTE: Do not place the `tctl` and `tsh` clients in the System32 directory, as this can cause issues when using WinSCP. Use %SystemRoot% (C:\Windows) or %USERPROFILE% (C:\Users\) instead. ``` **Linux** All of the Teleport binaries in Linux installations include the `tctl` and `tsh` clients. For more options (including RPM/DEB packages and downloads for i386/ARM/ARM64) see our [installation page](https://goteleport.com/docs/ver/17.x/installation.md). ``` $ curl -O https://cdn.teleport.dev/teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ tar -xzf teleport-v${TELEPORT_VERSION?}-linux-amd64-bin.tar.gz $ cd teleport $ sudo ./install Teleport binaries have been copied to /usr/local/bin ``` * An OCI Compute instance to host a Teleport service. * 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, run the following command, assigning teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 17.7.20 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. Create the Oracle joining token Configure your Teleport Auth Service with a special dynamic token which will allow services from your OCI tenants to join your Teleport cluster. Create the following `token.yaml` file with an `oracle.allow` rule specifying the Oracle tenant(s), compartment(s), and region(s) in which your OCI Compute instances will run: ``` # token.yaml kind: token version: v2 metadata: # The token name is not a secret because instances must prove that they are # running in your Oracle tenant to use this token. name: oracle-token spec: # Use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop). roles: [Node] # Set the join method allowed for this token. join_method: oracle oracle: allow: # OCID of the tenancy to allow instances to join from. Required. - tenancy: "ocid1.tenancy.oc1.." # (Optional) OCIDs of compartments to allow instances to join from. Only the direct parent # compartment applies; i.e. nested compartments are not taken into account. # If empty, instances can join from any compartment in the tenancy. parent_compartments: ["ocid1.compartment.oc1..."] # (Optional) Regions to allow instances to join from. Both full names ("us-phoenix-1") # and abbreviations ("phx") are allowed. If empty, instances can join from any region. regions: ["example-region"] ``` Run the following command to create the token: ``` $ tctl create token.yaml ``` ## Step 2/5. Configure permissions Every OCI Compute instance needs permission to authenticate itself with the Oracle Cloud API so the presigned request can succeed. ### Create a dynamic group In the OCI console, navigate to [Identity/Domains](https://cloud.oracle.com/identity/domains). Select the currently active domain, then select **Dynamic groups**. Click **Create dynamic group**. Create a group with the following matching rule, assigning compartment-id to the OCID of the compartment your instance is in: ``` Any {instance.compartment.id = 'compartment-id'} ``` ![Create dynamic group](/docs/assets/images/oracle-join-dynamic-group@2x-8f9df642573d1bbc95130c349d72f4ef.png) --- TIP To minimize unnecessary permissions, configure your matching rules to match the rules in the token created in step 1. --- ### Add policy to group In the OCI console, navigate to [Identity/Domains/Policy](https://cloud.oracle.com/identity/domains/policies). Click **Create Policy**. Create the following policy, assigning identity-domain to the name of the selected identity domain: ``` Allow dynamic-group 'identity-domain'/'join-teleport' to inspect authentication in tenancy ``` ![Create policy](/docs/assets/images/oracle-join-policy@2x-f0d8738e86ce93dc114e1dc14d8b8207.png) ## Step 3/5. Install Teleport Install Teleport on your OCI Compute instance. To install a Teleport Agent on your Linux server: The easiest installation method, for *Teleport versions 17.3 and above*, is the cluster install script. It will use the best 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 ``` On *older Teleport versions*: 1. Assign edition to one of the following, depending on your Teleport edition: | Edition | Value | | --------------------------------- | ------------ | | Teleport Enterprise Cloud | `cloud` | | Teleport Enterprise (Self-Hosted) | `enterprise` | | Teleport Community Edition | `oss` | 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=teleport.example.com:443 $ 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=teleport.example.com:443 $ 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.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](https://goteleport.com/docs/ver/17.x/installation/linux.md). ## Step 4/5. Configure your services The Oracle join method can be used for Teleport processes running the SSH (`Node`), Proxy, Kubernetes, Application, Database, or Windows Desktop Services. The Teleport process should be run directly on an OCI Compute instance. Configure your Teleport process with a custom `teleport.yaml` file. Use the `join_params` section with `token_name` matching your token created in Step 1 and `method: oracle` as shown in the following example config: ``` # /etc/teleport.yaml version: v3 teleport: join_params: token_name: oracle-token method: oracle proxy_server: https://teleport.example.com:443 ssh_service: enabled: true auth_service: enabled: false proxy_service: enabled: false ``` ## Step 5/5. Launch your Teleport process 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. **Package Manager** On the host where you will run your Teleport instance, enable and start Teleport: ``` $ sudo systemctl enable teleport $ sudo systemctl start teleport ``` **TAR Archive** On the host where you will run your Teleport instance, create a systemd service configuration for Teleport, enable the Teleport service, and start Teleport: ``` $ sudo teleport install systemd -o /etc/systemd/system/teleport.service $ 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`. Once you have started Teleport, confirm that your service is able to connect to and join your cluster. ## Troubleshooting ### Join fails with error `oci api error: Not Found` This error likely means that the instance does not have the required permissions. Check if the identity domain you created the dynamic group in has the Compute service active; if it doesn't, try creating the group in a domain that does.