# 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 their signed OCI instance identity certificate to the Auth Service, along with a cryptographic signature proving ownership of the instance's private key. The Auth Service verifies the instance identity certificate was signed by Oracle's root CAs and that the signature is valid. The certificate verifies the instance's tenancy, compartment, and instance ID and matches them against rules configured in an Oracle joining token. Instances running a version older than Teleport v18.4.0 do not send the instance identity certificate, instead they send 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/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/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. * One of the following client tools for managing Teleport resources: - The `tctl` CLI, which you can install along with Teleport on your workstation ([documentation](https://goteleport.com/docs/installation.md)) on your workstation. - [Teleport Terraform provider](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider.md) - [Teleport Kubernetes operator](https://goteleport.com/docs/zero-trust-access/infrastructure-as-code/terraform-provider.md) ## 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. You can create the token with `tctl` as well as the Teleport Terraform provider or Kubernetes operator: **tctl** 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. In Teleport v18.4.0 or higher you can also specify exact compute instance OCIDs that will be allowed. ``` # 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"] # (Optional) OCIDs of specific compute instances that should be allowed to join. # If empty, any instance matching the other fields is allowed. # The instances field is supported in Teleport v18.4.0+. instances: ["ocid1.instance.oc1.."] ``` Run the following command to create the token: ``` $ tctl create token.yaml ``` **Terraform** Add the following resource to your Terraform configuration, replacing values as indicated: ``` resource "teleport_provision_token" "oracle-token" { version = "v2" metadata = { name = "oracle-token" } labels = { // This label is added on the Teleport side by default "teleport.dev/origin" = "dynamic" } spec = { // use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop) roles = ["Node"] 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"] # (Optional) OCIDs of specific compute instances that should be allowed to join. # If empty, any instance matching the other fields is allowed. # The instances field is supported in Teleport v18.4.0+. instances = ["ocid1.instance.oc1.."] }, ] } } } ``` **Kubernetes** Add the following Kubernetes resource manifest, replacing values as indicated: ``` apiVersion: "resources.teleport.dev/v2" kind: TeleportProvisionToken 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" labels: # This label is added on the Teleport side by default "teleport.dev/origin": "dynamic" 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"] # (Optional) OCIDs of specific compute instances that should be allowed to join. # If empty, any instance matching the other fields is allowed. # The instances field is supported in Teleport v18.4.0+. instances: ["ocid1.instance.oc1.."] ``` ## Step 2/5. Configure permissions On Teleport versions older than v18.4.0, every OCI compute instance needs IAM permissions to authenticate itself with the Oracle Cloud API. Newer Teleport versions do not require any permissions. The permissions are only required if either the Auth Service or the joining instance is running a Teleport version older than v18.4.0. Configuring OCI IAM Permissions ### 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 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 ``` ## 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.