Set up IAP TCP forwarding with an IP address or hostname in a Google Cloud or non-Google Cloud environment

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 resources by using the resource private IP address or hostname. If you have external resources in non-Google Cloud 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 non-Google Cloud resources 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.

The following procedures provide gcloud examples for completing the tasks. For information about how to interact with destination groups by using the APIs, see REST Resource: projects.iap_tunnel.locations.destGroups

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 iap tcp dest-groups create YOUR_GROUP_NAME \
    --region=REGION \
    --ip-range-list=IP_RANGE_LIST \
    --fqdn-list=FQDN_LIST

Replace the following:

  • YOUR_GROUP_NAME: Your group name. A group name can contain only lowercase letters (a-z) and dashes (-).
  • REGION: The region in which to create the destination group, such as us-central1.
  • IP_RANGE_LIST: Optional. 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: Optional. 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 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 iap tcp dest-groups add-iam-policy-binding \
    --member=MEMBER \
    --role=ROLE \
    --dest-group=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 destination group name.
  • 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 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 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.16.1.2. 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.16.1.2, run the following command:

gcloud compute ssh 172.16.1.2 \
    --region=us-central1 \
    --dest-group=DESTINATION_GROUP_NAME \
    --network=default \
    --tunnel-through-iap

Replace DESTINATION_GROUP_NAME with the destination group name.

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 the path to the file containing the SSH private keys as a parameter for the SSH command, as shown in the following example:

gcloud compute ssh 172.16.1.2 \
    --region=us-central1 \
    --dest-group=DESTINATION_GROUP_NAME \
    --network=default \
    --tunnel-through-iap \
    -- -i ~/.ssh/google_compute_engine

Replace DESTINATION_GROUP_NAME with the destination group name.

If you want to login as a specific user, use the fomat USER@IP instead of specifying the IP only:

gcloud compute ssh user@172.16.1.2 \
    --region=us-central1 \
    --dest-group=DESTINATION_GROUP_NAME \
    --network=default \
    --tunnel-through-iap

If the account is password protected, you must enter a password. If the account is protected by a private or public SSH key pair, you must specify it using the -- -i flag as specified above.

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.16.1.2:8085, run the following command:

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

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

After you establish a tunnel, you can use any tool, such as PuTTy, to establish a connection.

SCP example

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

gcloud compute scp file.txt 172.16.1.2:~/ \
    --region=us-central1 \
    --dest-group=destination-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.16.1.2, add an entry to your ~/.ssh/config configuration or equivalent, as shown in the following example:

Host example
ProxyCommand gcloud compute start-iap-tunnel 172.16.1.2 %p \
    --listen-on-stdin \
    --region=us-central1 \
    --dest-group=destination-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 compute start-iap-tunnel %h %p 

    --listen-on-stdin 

    --region=us-central1 

    --dest-group=destination-group-name 

    --network=default
    --verbosity=warning

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