Using IAP TCP forwarding with an IP address or hostname

This page describes how to set up and use the Identity-Aware Proxy (IAP) TCP forwarding with an IP address or hostname feature.

To use the IAP TCP forwarding with an IP address or hostname feature, you must have a BeyondCorp Enterprise license.

Overview

You can use the Google Cloud CLI to create tunnels to endpoints by using the endpoint private IP address or hostname. If you have external resources (on premises or in other clouds) connected to Google Cloud through Cloud Interconnect or a VPN, you can use IAP TCP forwarding with those resources.

Before you begin

If you need to tunnel to resources outside Google Cloud, you must have hybrid connectivity configured. Hybrid connectivity is required for connecting your external resources (on-premises or other clouds) to Google Cloud. For more information, see the Cloud Interconnect or Cloud VPN documentation.

Your cloud router must advertise the IAP-TCP IP range (35.235.240.0/20), so that the destinations send response traffic back through Cloud VPN or Cloud Interconnect and not through the internet. If you do not have this configuration, you cannot create tunnels to resources external to your Google Cloud project.

To configure your cloud router to advertise the IAP-TCP IP range, 35.235.240.0/20, follow the instructions in Advertising custom IP ranges.

Creating a tunnel destination group

When you configure a tunnel, you specify a destination group to use for permission checks. Tunnel destination groups represent resources that have the same tunnel access restrictions. You can create any number of destination groups, each with any number of matching IP ranges or FQDN. Destination groups can overlap for more flexibility.

When creating a destination group, you must specify a region. For the best results, the region you specify should match the location of the destination resources. For example, if the resources are connected by a VPN, you should use the region of the VPN gateway. The destination group name can only contain lower case letters (a-z) and dashes (-)

To create a destination group, you must have the iap.tunnelDestGroups.create permission, which you can grant through the iap.tunnelDestGroupEditor role. To grant a single role, see Grant a single role in the IAM documentation.

To create a destination group, run the following example command:

gcloud alpha iap tcp dest-groups create your-group-name \
    --region=REGION \
    --ip-range-list=IP_RANGE_LIST \
    --fqdn-list=FQDN_LIST
    

Replace the following:

  • REGION: The region in which to create the destination group, such as us-central1.
  • IP_RANGE_LIST: The IP range list, which consists of comma-separated ranges using CIDR notation, such as 10.1.2.0/24,172.0.0.0/8.
  • FQDN_LIST: The FQDN list is a comma-separated list of hostnames, such as *.internal.company.com. If an FQDN entry has a wildcard prefix, it will match any hostname with the specified ending. Otherwise, it requires an exact match. If a request matches any IP range or FQDN, it is considered a match.

If you are unsure of what groups already exist, run the following command to list the groups:

gcloud alpha iap tcp dest-groups list \
    --region=REGION
    

See destination group gcloud commands for an overview of how to manage destination groups.

Configuring tunnel permissions

To create a tunnel, you must have the iap.tunnelDestGroups.accessViaIAP permission on the relevant destination group. You can grant the permission through the iap.tunnelResourceAccessor role.

To configure permissions on destinations groups, you must have the iap.tunnelDestGroups.setIamPolicy permission, which you can grant through the iap.admin role.

To grant permissions, run the following example command:

gcloud alpha iap tcp dest-groups add-iam-policy-binding \
    --member=MEMBER \
    --role=ROLE \
    --group-name=GROUP_NAME \
    --region=REGION
  

Replace the following:

  • MEMBER: The email address for the user, such as user:exampleuser@company.com.
  • ROLE: The required IAP role, roles/iap.tunnelResourceAccessor.
  • GROUP_NAME: The name of your group.
  • REGION: The name of the region, such as us-central1.

Understanding tunnel usage

There are three gcloud CLI commands that you can use when working with IAP-TCP: start-iap-tunnel, ssh, and scp.

The alpha versions of the IAP-TCP commands have been updated to support IP- and FQDN-based tunneling. To switch to IP address or FQDN, do the following when using the commands:

  • Specify gcloud alpha instead of gcloud.
  • Specify an IP address or FQDN instead of the instance name.
  • Use --region instead of --zone.
  • Use --dest-group to specify the destination group to use.
  • Use --network to specify the name of the VPC network to use.

The IP address you specify must be the private IP address of the destination. You cannot use IAP-TCP with public IP addresses. If you use FQDN, it must resolve to the private IP address of the destination. Note that the name resolution is done from within the VPC network you specify, not from the client's network. For example, if you are attempting to create a tunnel to vm.corp.company.com, the step that converts vm.corp.company.com to an IP address happens within the context of the VPC network, not your local network.

The region you specify must match the region of the destination group.

The network you specify must match the name of the VPC network that has access to the destination. A typical network name is default. You can view the list of network names on the VPC networks page in the Google Cloud console, or you can retrieve the list of network names by running the following command:

gcloud compute networks list --format='value(name)'

Examples

The following examples use an example IP address of 172.1.2.3. Each command can also take an FQDN (for example, example.internal.company.com) in place of the IP address.

SSH example

To start an SSH session to 172.1.2.3, run the following command:

gcloud alpha compute ssh 172.1.2.3 \
    --region=us-central1 \
    --dest-group=your-group-name \
    --network=default \
    --tunnel-through-iap
    

Note that --plain is implied, so there is no attempt to automatically manage and push SSH keys when using an IP address.

If you receive the error Permission denied (publickey), the command did not find the file that contains the SSH keys. To resolve this issue, add -- -i ~/.ssh/google_compute_engine as a parameter for the SSH command:

gcloud alpha compute ssh 172.1.2.3 \
    --region=us-central1 \
    --dest-group=your-group-name \
    --network=default \
    --tunnel-through-iap \
    -- -i ~/.ssh/google_compute_engine
    

Tunnel example

To establish a tunnel to a different TCP port, use the start-iap-tunnel command. To create a tunnel from localhost:8022 to port 172.1.2.3:8085, run the following command:

gcloud alpha compute start-iap-tunnel 172.1.2.3 8085 \
    --local-host-port=localhost:8022 \
    --region=us-central1 \
    --dest-group=your-group-name \
    --network=default

Note that the destination machine must be listening to port 8085 in this example.

SCP example

To SCP a file to 172.1.2.3, run the following command:

gcloud alpha compute scp file.txt 172.1.2.3:~/ \
    --region=us-central1 \
    --dest-group=your-group-name \
    --network=default \
    --tunnel-through-iap

Note that --plain is implied, so there is no attempt to automatically manage and push SSH keys when using an IP address.

SSH ProxyCommand example

To use the command as a ProxyCommand that always tunnels to 172.1.2.3, add an entry to your ~/.ssh/config configuration or equivalent, as shown in the following example:

Host example
ProxyCommand gcloud alpha compute start-iap-tunnel 172.1.2.3 %p \
    --listen-on-stdin \
    --region=us-central1 \
    --dest-group=your-group-name \
    --network=default \
    --verbosity=warning
  

The ProxyCommand takes effect when you run the following command: ssh example

You can also set up the ProxyCommand to handle many hostnames, as shown in the following example:

Host *.internal.company.com
ProxyCommand gcloud alpha compute start-iap-tunnel %h %p 
--listen-on-stdin
--region=us-central1
--dest-group=your-group-name
--network=default --verbosity=warning

The ProxyCommand takes effect when you run the following command: ssh example.internal.company.com