Expose reverse tunnels to users

docs/admin-guide.md

@@ -30,9 +30,22 @@ this way:
 
 You can download binaries from [Github releases](https://github.com/gravitational/teleport/releases). 
 
-## Running
+## Nomenclature
 
-Teleport supports only a handful of commands
+Before diving into configuring and running Teleport, it helps to take a look at the [Teleport Architecture](/architecture) 
+and go over the key concepts this document will be referring to:
+
+|Concept   | Description
+|----------|------------
+|Node      | Synonym to "server" or "computer", something one can "SSH to". A node must be running `teleport` daemon running with "node" role/service turned on.
+|Certificate Authority (CA) | A pair of public/private keys Teleport uses to manage access. A CA can sign a public key of a user or node establishing their cluster membership.
+|Teleport Cluster | A Teleport Auth Service contains two CAs. One is used to sign user keys and the other signs node keys. A collection of nodes connected to the same CA is called a "cluster". 
+|Cluster Name | Every Teleport cluster must have a name. If a name is not supplied via `teleport.yaml` configuration file, a GUID will be generated. **IMPORTANT:** renaming a cluster invalidates its keys and all certificates it had created.
+|Trusted Cluster | Teleport Auth Service can allow 3rd party users or nodes to connect if their public keys are signed by a trusted CA. A "trusted cluster" is a pair of public keys of the trusted CA. It can be configured via `teleport.yaml` file.
+
+## Running Teleport Servers
+
+The Teleport daemon supports the following commands:
 
 |Command     | Description
 |------------|-------------------------------------------------------
@@ -85,8 +98,8 @@ Teleport services listen on several ports. This table shows the default port num
 |----------|------------|-------------------------------------------
 |3022      | Node       | SSH port. This is Teleport's equivalent of port `#22` for SSH.
 |3023      | Proxy      | SSH port clients connect to. A proxy will forward this connection to port `#3022` on the destination node.
+|3024      | Proxy      | SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server.
 |3025      | Auth       | SSH port used by the Auth Service to serve its API to other nodes in a cluster.
-|3024      | Tunnel     | SSH port used to create "reverse SSH tunnels" from behind-firewall environments into a trusted proxy server.
 |3080      | Proxy      | HTTPS connection to authenticate `tsh` users and web users into the cluster. The same connection is used to serve a Web UI.
 
 
@@ -225,7 +238,9 @@ ssh_service:
     labels:
         role: master
         type: postgres
-    # See explanation of commands in "Labeling Nodes" section below
+    # List (YAML array) of commands to periodically execute and use
+    # their output as labels. 
+    # See explanation of how this works in "Labeling Nodes" section below
     commands:
     - name: hostname
       command: [/usr/bin/hostname]
@@ -241,11 +256,23 @@ proxy_service:
     # SSH sessions by connecting to this port
     listen_addr: 0.0.0.0:3023
 
-    # Reverse tunnel listening address. An auth server (CA) can establish an outbound 
-    # (from behind the firwall) connection to this address. This will allow users of
-    # the outside CA to connect to behind-the-firewall nodes.
+    # Reverse tunnel listening address. An auth server (CA) can establish an 
+    # outbound (from behind the firwall) connection to this address. 
+    # This will allow users of the outside CA to connect to behind-the-firewall 
+    # nodes.
     tunnel_listen_addr: 0.0.0.0:3024
 
+    # List (array) of other clusters this CA trusts.
+    trusted_clusters:
+      - key_file: /path/to/main-cluster.ca
+        # Comma-separated list of OS logins allowed to users of this 
+        # trusted cluster
+        allow_logins: john,root
+        # Establishes a reverse SSH tunnel from this cluster to the trusted
+        # cluster, allowing the trusted cluster users to access nodes of this 
+        # cluster
+        tunnel_addr: 80.10.0.12:3024
+
     # The HTTPS listen address to serve the Web UI and also to authenticate the 
     # command line (CLI) users via password+HOTP
     web_listen_addr: 0.0.0.0:3080
@@ -420,7 +447,7 @@ The latter two tokens can be deleted (revoked) via `tctl tokens del` command:
 Token 696c0471453e75882ff70a761c1a8bfa has been deleted
 ```
 
-### Labeling Nodes
+## Labeling Nodes
 
 In addition to specifying a custom nodename, Teleport also allows to apply arbitrary
 key:value pairs to each node. They are called labels. There are two kinds of labels:
@@ -451,6 +478,126 @@ Node Name     Node ID          Address         Labels
 turing        d52527f9-b260    10.1.0.5:3022   kernel=3.19.0-56,uptime=up 1 hour, 15 minutes
 ```
 
+## Trusted Clusters
+
+Teleport allows to partition your infrastructure into multiple clusters. Some clusters can be 
+located behind firewalls without any open ports. They can also have different access rights.
+
+As [explained above](#nomenclature), a Teleport Cluster has a name and is managed by a 
+`teleport` daemon with "auth service" enabled.
+
+Lets assume we need to place some servers behind a firewall, and we only want Teleport 
+user "john" to have access to them. Assume we already have our primary Teleport cluster 
+and our users set up. Say, this cluster is called "main". 
+
+Now, to add behind-the-firewall machines and restrict access only to "john", we will have 
+to do the following:
+
+1. Create a new cluster for behind-the-firewall machines. Lets call it "cluster-b".
+2. Add "cluster-b" to the list of `trusted clusters` of "main".
+3. Add "main" cluster to the list of `trusted clusters` of "cluster-b".
+4. Tell "cluster-b" to open a reverse tunnel to "main" cluster, this SSH tunnel will connect from behind a firewall out to the proxy service of "main" cluster.
+5. Tell "cluster-b" to only allow "john" from cluster "main".
+6. John will have to use `--cluster` flag when using `tsh` command to connect to nodes inside of "cluster-b".
+
+Lets look into the details of each step. First, lets configure two independent (at first) 
+clusters: 
+
+```
+auth_service:
+  enabled: yes
+  cluster_name: main
+```
+
+And our behind-the-firewall cluster:
+
+```
+auth_service:
+  enabled: yes
+  cluster_name: cluster-b
+```
+
+Start both servers. At this point they do not know about each other.
+Now, export their public CA keys:
+
+On "main":
+
+```
+> tctl auth export > main-cluster.ca
+```
+
+On "cluster-b":
+
+```
+> tctl auth export > b-cluster.ca
+```
+
+Now, modify the YAML configuration of both clusters to connect them.
+
+On "main" (running on 62.28.10.1)
+
+```yaml
+auth_service:
+  enabled: yes
+  cluster_name: main
+  trusted_clusters:
+      - key_file: /path/to/b-cluster.ca
+```
+
+On "cluster-b":
+
+```yaml
+auth_service:
+  enabled: yes
+  cluster_name: cluster-b
+  trusted_clusters:
+      - key_file: /path/to/main-cluster.ca
+        # This line contains comma-separated list of OS logins allowed
+        # to users from this trusted cluster
+        allow_logins: john
+        # This line establishes a reverse SSH tunnel from 
+        # cluster-b to main:
+        tunnel_addr: 62.28.10.1
+```
+
+Now, if you restart `teleport` auth service on both clusters, they should trust each
+other. To verify, run this on "cluster-b":
+
+```
+> tctl auth ls
+CA keys for the local cluster cluster-b:
+
+CA Type     Fingerprint
+-------     -----------
+user        xxxxxxxxxxxxxxx
+host        zzzzzzzzzzzzzzz
+
+CA Keys for Trusted Clusters:
+
+Cluster Name     CA Type     Fingerprint                     Allowed Logins
+------------     -------     -----------                     --------------
+main             user        zzzzzzzzzzzzzzzzzzzzzzzzzzz     john
+main             host        xxxxxxxxxxxxxxxxxxxxxxxxxxx     N/A
+```
+
+Notice that each cluster is shown as two CAs: one is used to establish trust between nodes,
+and another one is for trusting users. 
+
+Now, John, having direct access to a proxy server of cluster "main" (lets call it main.proxy) can 
+use `tsh` command to see which clusters are online:
+
+```
+> tsh --proxy=main.proxy clusters
+```
+
+John can also list all nodes in the cluster-b:
+
+```
+> tsh --proxy=main.proxy --cluster=cluster-b ls
+```
+
+Similarly, by passing `--cluster=cluster-b` to `tsh` John can login into cluster-b nodes.
+
 ## Using Teleport with OpenSSH
 
 Teleport is a fully standards-compliant SSH proxy and it can work in environments with 
@@ -470,7 +617,7 @@ on a node which runs Teleport auth server and probably must be done by a Telepor
 administrator:
 
 ```bash
-> tctl authorities --type=host export > cluster_node_keys
+> tctl auth --type=host export > cluster_node_keys
 ```
 
 On your client machine, you need to import these keys. It will allow your OpenSSH client
@@ -516,7 +663,7 @@ have to configure `sshd` to trust Teleport CA.
 Export the Teleport CA certificate into a file:
 
 ```bash
-> tctl authorities --type=user export > cluster-ca.pub
+> tctl auth --type=user export > cluster-ca.pub
 ```
 
 Copy this file to every node running `sshd`, for example into `/etc/ssh/teleport-ca.pub`

docs/faq.md

@@ -4,22 +4,38 @@
 
 Teleport has completed a security audit from a nationally recongized technology security company. So we are comfortable with the use of Teleport from a security perspective. However, Teleport is still a relatively young product so you may find bugs and other issues. We are actively supporting Teleport and addressing any issues that are submitted to the [github repo](https://github.com/gravitational/teleport).
 
+**Can I connect to nodes behind a firewall via SSH with Teleport?**
+
+Yes, Teleport supports reverse SSH tunnels out of the box. To configure behind-firewall clusters
+refer to [Trusted Clusters](admin-guide/#trusted-clusters) section of the Admin Manual.
+
+
 **Can I use OpenSSH client to connect to servers in a Teleport cluster?**
 
 Yes. Take a look at [Using OpenSSH client](user-manual.md#integration-with-openssh) section in the User Manual
 and [Using OpenSSH servers](admin-guide.md) in the Admin Manual.
 
-**Which TCP ports does Teleport uses?**
+**What TCP ports does Teleport use?**
 
 [Ports](admin-guide.md#ports) section of the Admin Manual covers it.
 
+**Does Teleport support 3rd party Authentication?**
+
+Teleport supports Google Apps out of the box, see [OpenID/OAuth2](admin-guide/#openid-oauth2) for how to configure it.
+Other OpenID providers can easily be added - Teleport code is open and your contributions are welcome! :)
+
+**Does Teleport support Authentication via LDAP or Active Directory?**
+
+Gravitational offers this feature as part of the commercial support for Teleport.
+
 **Do you offer commercial support for Teleport?**
 
 Yes, we offer commercial support which includes:
 
 * Commercial version of Teleport which includes multi-cluster capabilities, 
   integration with enterprise identity management (LDAP and others) and custom features.
 * Option of fully managed Teleport clusters running on your infrastructure.
+* Shipping of the audit logs to 3rd party log management systems.
 * Commercial support with guaranteed response times.
 
 Reach out to `sales@gravitational.com` if you have questions about commerial edition of Teleport.

docs/user-manual.md

@@ -4,8 +4,8 @@ This User Manual covers usage of the Teleport client tool `tsh`. In this
 document you will learn how to:
 
 * Securely login into interactive shell on remote cluster nodes.
-* Execute commands on cluster nodes.
 * Securely copy files to and from cluster nodes.
+* Connect to SSH clusters behind firewals without any open ports using SSH reverse tunnels.
 * Explore a cluster and execute commands on those nodes in a cluster that match your criteria.
 * Share interactive shell sessions with colleagues or join someone else's session.
 * Replay recorded interactive sessions.
@@ -19,16 +19,17 @@ usage: tsh [<flags>] <command> [<command-args> ...]
 Gravitational Teleport SSH tool
 
 Commands:
-  help       shows help for a given command
-  ssh        connect and log into a remote host(s) for executing commands
-  scp        secure copy file(s) to a remote SSH host(s)
-  share      invite a colleague to share your current terminal
-  join       join a colleague who invited you into his SSH session
-  ls         list remote SSH hosts available via SSH proxy (bastion)
-  login      logs in the SSH proxy and enables usage of OpenSSH client
-  logout     logs off the SSH proxy
-  agent      starts SSH session agent for compatibility with OpenSSH client
-  configure  dump a sample profile file into stdout
+  help         Show help.
+  version      Print the version
+  ssh          Run shell or execute a command on a remote SSH node
+  join         Join the active SSH session
+  play         Replay the recorded SSH session
+  scp          Secure file copy
+  ls           List remote SSH nodes
+  clusters     List available Teleport clusters
+  agent        Start SSH agent on unix socket
+  login        Log in to the cluster and store the session certificate to avoid login prompts
+  logout       Delete a cluster certificate
 
 Notes:
 
@@ -214,7 +215,12 @@ This command logs you into the cluster with a very short-lived (1 minute) tempor
 tsh --proxy=work --ttl=1 ssh
 ```
 
-You will be logged out after one minute.
+You will be logged out after one minute, but if you want to log out immediately, you can 
+always do:
+
+```bash
+tsh --proxy=work logout
+```
 
 ## Copying Files
 
@@ -279,6 +285,43 @@ Or you can share the session ID and she can join you through her terminal by typ
 > tsh --proxy=work join 7645d523-60cb-436d-b732-99c5df14b7c4
 ```
 
+## Connecting to SSH Clusters behind Firewalls
+
+Teleport supports creating clusters of servers located behind firewalls without any open ports.
+This works by creating reverse SSH tunnels from behind-firewall environments into a Teleport
+proxy you have access to. This feature is called "Trusted Clusters". 
+
+Assuming your "work" Teleport server is configured with a few trusted clusters, this is how you can
+see a list of them:
+
+```bash
+> tsh --proxy=work clusters
+
+Cluster Name     Status
+------------     ------
+staging          online
+production       offline
+```
+
+Now you can use `--cluster` flag with any `tsh` command. For example, to list SSH nodes that
+are members of "production" cluster, simply do:
+
+```bash
+> tsh --proxy=work --cluster=production ls
+Node Name     Node ID       Address            Labels
+---------     -------       -------            ------
+db-1          xxxxxxxxx     10.0.20.31:3022    kernel:4.4
+db-2          xxxxxxxxx     10.0.20.41:3022    kernel:4.2
+```
+
+Similarly, if you want to SSH into `db-1` inside "production" cluster:
+
+```bash
+> tsh --proxy=work --cluster=production ssh db-1
+```
+
+For more details on configuring Trusted Clusters please look at the Admin Guide.
+
 ## Troubleshooting
 
 If you encounter strange behaviour, you may want to try to solve it by enabling

fixtures/trusted_clusters/cluster-a

@@ -0,0 +1,2 @@
+@cert-authority *.cluster-a ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDUiGSWo4UDAsAmxdcp4ltllDz7RoyWxVx6Rh0lz5u/PTwLAz6BIuPSilBnytecD1ALBAwG9EK6YXlGC/cqLmaq8/00nQ4cWZK6X/3eEsAxjo85FwSeIq7gWHZEjv3adipo4alTCcJ9ZFQcRx1h699Un5gvHdS6AQBv3/IjWbvb1PYhq9jQXNKslSTAVyB2RWHkuOXDtCpwNWyMNm00+kOD+ZZBHx5TADIOFKlqNPisiPMt8YQAniMMQh0Y9H33Vzd8GWn1UgEET+hmJk/NZPzgZ3uWOnnxUpgzFGppSeJHfcYd8CCaUeHhCQv8iwRwv+k6HEMnlCNJuwG3Q+qWc0ar type=host
+@cert-authority *.cluster-a ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDryH6fvORZtkKA3/lxnX4puqy8nUJffaNGLTa08N9aEtlP6fkkF3l+yCyZ70sjz94sa7Gb3naEm5GwwPjeLGWE3ctcsxCQ6I9EWoRHTSHobw6g/OFaMWh29/QFsWkLRRxFMFRVq0C+sT0xEZHQhaK8SPhIlXF7eE8PMEKB4tlq+6VqZrE8HHiWCUImipDKKyaAGRemAKMuk+MkDNXJX0p6XYVnL+g39PE6w324hk8tq/4vmpZ3Pri6ABOZhrx0asC0XBPMoDiGCo09xZDQLB3NN2qQVCtbGNPxXdYiOGx1yMxJuTFxtd05qpQaNrX5bSDkEUJnBwmWHHlP35EFnZwh type=user

lib/auth/clt.go

@@ -337,7 +337,7 @@ func (c *Client) DeleteReverseTunnel(domainName string) error {
 	// HTTP route will fail producing generic not found error
 	// instead we catch the error here
 	if !cstrings.IsValidDomainName(domainName) {
-		return trace.BadParameter("'%v' is a bad domain name", domainName)
+		return trace.BadParameter("'%v' is not a valid FQDN", domainName)
 	}
 	_, err := c.Delete(c.Endpoint("reversetunnels", domainName))
 	return trace.Wrap(err)