This page explains how you can use Identity-Aware Proxy (IAP) TCP forwarding toenable administrative access to VM instances that do not have external IPaddresses or do not permit direct access over the internet.
IAP TCP forwarding allows you to establish an encrypted tunnelover which you can forward SSH, RDP, and other traffic to VM instances.IAP TCP forwarding also provides you fine-grained control overwhich users are allowed to establish tunnels and which VM instances users areallowed to connect to.
To learn more about how IAP TCP forwarding works, see theTCP forwarding overview.
Preparing your project for IAP TCP forwarding
This section walks you through the necessary steps to enable IAPTCP forwarding in your Google Cloud project.
Create a firewall rule
To allow IAP to connect to your VM instances, create a firewallrule that:
- applies to all VM instances that you want to be accessible byusing IAP.
- allows ingress traffic from the IP range
35.235.240.0/20
. Thisrange contains all IP addresses that IAP uses for TCP forwarding. allows connections to all ports that you want to be accessible byusing IAP TCP forwarding, for example, port
22
for SSH and port3389
for RDP.
Console
To allow RDP and SSH access to all VM instances in your network, do the following:
- Open the Firewall Rules page.
Open the Firewall Rules page
- On the Firewall Rules page, click Create firewall rule.
- Configure the following settings:
- Name:
allow-ingress-from-iap
- Direction of traffic: Ingress
- Target: All instances in the network
- Source filter: IP ranges
- Source IP ranges:
35.235.240.0/20
- Protocols and ports: Select TCP and enter
22,3389
to allow both RDP and SSH.
- Name:
- Click Create.
gcloud
To allow RDP access to all VM instances in your network, run:
gcloud compute firewall-rules create allow-rdp-ingress-from-iap \ --direction=INGRESS \ --action=allow \ --rules=tcp:3389 \ --source-ranges=35.235.240.0/20
For SSH access, run:
gcloud compute firewall-rules create allow-ssh-ingress-from-iap \ --direction=INGRESS \ --action=allow \ --rules=tcp:22 \ --source-ranges=35.235.240.0/20
For other protocols, run
gcloud compute firewall-rules create allow-ingress-from-iap \ --direction=INGRESS \ --action=allow \ --rules=tcp:PORT \ --source-ranges=35.235.240.0/20
where PORT
is the port used by the protocol.
Grant permissions to use IAP TCP forwarding
To control which users and groups are allowed to use IAP TCPforwarding and which VM instances they're allowed to connect to, configureIdentity and Access Management (IAM) permissions.
We recommend granting all of the following roles for trusted administrators:
- roles/iap.tunnelResourceAccessor (project or VM)
- roles/compute.instanceAdmin.v1 (project)
Additionally, if you are using OS Login (recommended), seeConfiguring OS Login roles on user accounts.If you are using service accounts, seethese instructions onhow to set up theserviceAccountUser role.
You can grant a user or group access to all VM instances in a project byconfiguring IAM permissions on the project level:
Console
- Open the IAM & Admin page in the Google Cloud console.
- On the IAM & Admin page, click Add and configure the following:
- New principals: Specify the user or group you want to grant access.
- Select a role: Select Cloud IAP > IAP-Secured Tunnel User.
- Optionally, click Add condition and configure a member restriction:
- Title: Enter a name for the restriction.
- Expression: Enter a condition that a user must meet before being allowed to use IAP for TCP forwarding.
For example, the following CEL expression restricts access to port 22:
destination.port == 22
You can also restrict access by access level:
destination.port == 22 &&"FULL_ACCESS_LEVEL_NAME" in request.auth.access_levels
Where
FULL_ACCESS_LEVEL_NAME
is an existing access level and uses the following format:accessPolicies/POLICY_NAME/accessLevels/ACCESS_LEVEL_NAME
- Click Add another role and configure the following:
- Select a role Select Compute Engine > Compute Instance Admin (v1).
- Click Save.
gcloud
Grant the two roles to the user by running the following commands:
gcloud projects add-iam-policy-binding PROJECT_ID \ --member=user:EMAIL \ --role=roles/iap.tunnelResourceAccessorgcloud projects add-iam-policy-binding PROJECT_ID \ --member=user:EMAIL \ --role=roles/compute.instanceAdmin.v1
Replace the following:
PROJECT_ID
: ID of the projectEMAIL
: email address of the user you want to grant access,for exampleuser@example.com
.
If desired, you can instead configure the iap.tunnelResourceAccessor
role by VM(the other roles must be on the project):
Console
- Open the IAP admin page and select the SSH and TCP Resources tab.
Open the IAP admin page
- On the SSH and TCP Resources tab of the IAP admin page, select the VM instances that you want to configure.
- Click Show info panel if the info panel is not visible.
Click Add member and configure the following:
- New principals: Specify the user or group you want to grant access.
- Select a role: Select Cloud IAP > IAP-Secured Tunnel User.
Optionally, click Add condition and configure a member restriction:
- Title: Enter a name for the restriction.
- Expression: Enter a condition that a user must meet before being allowed to use IAP for TCP forwarding.
For example, the following CEL expression restricts access to port 22:
destination.port == 22
You can also restrict access by access level:
See AlsoChandigarh Bus Stand | Chandigarh Bus Stand Contact NumberThe Future of the Jewellery Industry: Trends & Insights | Matter Of FormThe Top 20 Administrative Job Titles [with Descriptions]Everything You Need to Know About Platinum Ringsdestination.port == 22 && "FULL_ACCESS_LEVEL_NAME" in request.auth.access_levels
Where
FULL_ACCESS_LEVEL_NAME
is an existing [access level](/access-context-manager/docs/create-access-level) and uses the formataccessPolicies/POLICY_NAME/accessLevels/ACCESS_LEVEL_NAME
.- Click Save.
API
To edit your application's policy.json
file, follow the process below. See Managing access to IAP-secured resources for more information about using the IAM API to manage access policies.
Download the credentials file for your service account.
Go to the Service accounts page.Go to the service accounts page
Click the email address of your service account.
Click Edit.
Click Create key.
Select JSON as your key type.
Create a new key by clicking Create and closing the confirmation window that appears.
Your JSON credentials file has now been downloaded.
Export the following variables.
export IAP_BASE_URL=https://iap.googleapis.com/v1/projects/PROJECT_NUMBER/iap_tunnel# Replace with the path to your local service account's downloaded JSON fileexport JSON_CREDS=EXAMPLE.IAM.GSERVICEACCOUNT.COM.JSON# Replace POLICY_FILE.JSON with the name of JSON file to use for setIamPolicyexport JSON_NEW_POLICY=POLICY_FILE.JSON
Convert your service account credentials JSON file into an OAuth accesstoken using Oauth2l by running thefollowing command:
oauth2l header --json ${JSON_CREDS} cloud-platform
If this is your first time running the above command, when prompted:
- Get the verification code by clicking the displayed link and copyingthe code.
- Paste the verification code into your app prompt.
- Copy the returned bearer token.
- Export a new variable that's assigned to the value of your returnedbearer token.
export CLOUD_OAUTH_TOKEN=AUTHORIZATION_BEARER_TOKEN
If you've run this command before, export the following variable.
export CLOUD_OAUTH_TOKEN="$(oauth2l header --json ${JSON_CREDS} cloud-platform)"
Get the IAM policy for the Compute Engine instance usingthe
getIamPolicy
method. The empty data bit at the end turns thecurl
request into POST instead of GET.curl -i -H "${CLOUD_OAUTH_TOKEN}" \ ${IAP_BASE_URL}/zones/ZONE_NAME/instances/INSTANCE_ID or INSTANCE_NAME:getIamPolicy \ -d ''
Grant the
iap.tunnelResourceAccessor
role to your members bymodifying the IAM policy JSON file.Optionally, add member restrictions based on IAMConditions and access levels.
The following is an example of an edited
policy.json
file that bindstheiap.tunnelResourceAccessor
role to a group of VM instance admins,granting them access to IAP-secured tunnel resources.An IAM condition has been added to make the resourcesaccessible only to members in the VM instance admins group with a privateIP address of10.0.0.1
on port22
using thedestination.ip and destination.port IAM Conditions.They must also meet the requirements of the ACCESS_LEVEL_NAMEaccess level.Note that if a member has theOwner role, they have permission to use IAPfor TCP forwarding.
Example policy.json file{ "policy": { "bindings": [ { "role": "roles/iap.tunnelResourceAccessor", "members": ["group:instance-admins@example.com"], "condition": { "expression": "\"accessPolicies/POLICY_NAME/accessLevels/ACCESS_LEVEL_NAME\" in request.auth.access_levels && destination.ip == \"10.0.0.1\" && destination.port == 22", "title": "CONDITION_NAME" } } ] }}
To find a policy name, call accessPolicies.list:
GET https://accesscontextmanager.googleapis.com/v1/accessPolicies
Set your new
policy.json
file using thesetIamPolicy
method.curl -i -H "Content-Type:application/json" \ -H "$(oauth2l header --json ${JSON_CREDS} cloud-platform)" \ ${IAP_BASE_URL}/zones/ZONE_NAME/instances/INSTANCE_ID or INSTANCE_NAME:setIamPolicy \ -d @${JSON_NEW_POLICY}
Permissions details
The required permissions vary depending on how a user will use IAP TCP forwarding:
Scenarios | Permissions required | |
---|---|---|
All |
| |
Using gcloud compute [start-iap-tunnel, ssh, scp] |
| |
Using gcloud compute [ssh, scp] |
| |
VM using OS Login | Please see these instructions | |
Not using OS Login |
| |
SSH to VM using a service account |
| |
SSH from the browser | Please see these instructions |
For example, if a user wants to connect using gcloud compute ssh
to a VM not using OS Login,but that uses a service account, the user would need the following permissions:
iap.tunnelInstances.accessViaIAP
compute.instances.get
compute.instances.list
compute.projects.get
compute.instances.setMetadata
compute.projects.setCommonInstanceMetadata
compute.globalOperations.get
iam.serviceAccounts.actAs
Tunneling SSH connections
You can connect to Linux instances that don't have an external IP addressby tunneling SSH traffic through IAP.
When you use IAP tunnelling, the IAP proxies connect to the primary internalIPv4 address of nic0
on the VM.
Console
To connect to your instance, use the SSH button in theGoogle Cloud console.Your instance's access configuration(defined through IAM permissions) must allow TCPtunneling through IAP.
gcloud
To connect to your instance, use thegcloud compute ssh command. Yourinstance's access configuration(defined through IAM permissions) must allow TCPtunneling through IAP.
gcloud compute ssh INSTANCE_NAME
Replace INSTANCE_NAME with the name of the instance to SSH into.
If the instance doesn't have an external IP address, the connectionautomatically uses IAP TCP tunneling. If the instance doeshave an external IP address, the connection uses the external IP addressinstead of IAP TCP tunneling.
You can use the --tunnel-through-iapflag so that gcloud compute ssh
always uses IAP TCP tunneling.
Use the --internal-ipflag so that gcloud compute ssh
never uses IAP TCPtunneling and instead directly connects to the internal IP of the VM. Doingso is useful for clients that are connected to the same VPC network as thetarget VM.
IAP Desktop
You can use IAP Desktop to connect to a VM instance by using SSH and IAP TCP forwarding.
In the application, select File > Add Google Cloud project.
Enter the ID or name of your project and click OK.
In the Project Explorer window, right-click the VM instance youwant to connect to and select Connect.
For more information on IAP Desktop, see theGitHub project page.
PuTTY app
You can set up the PuTTY Windows terminal emulator app so that it usesIAP TCP forwarding to connect to a VM instance. Yourinstance's access configuration(defined through IAM permissions) must allow TCP tunneling through IAP.
Before you configure the PuTTY app, use the gcloud compute ssh
command onceto ensure that you have a private SSH key on your local computer and thatyour public SSH key is published to Compute Engine:
Open a command prompt and run the following command to connect to theVM instance:
gcloud compute ssh INSTANCE_NAME ` --tunnel-through-iap ` --project PROJECT_ID ` --zone ZONE
Replace the following:
- INSTANCE_NAME: name of the instance to connect to
- PROJECT_ID: project ID of the project the VM instance is located in
- ZONE: zone where the VM instance is located
If necessary, confirm that you want to generate SSH keys by pressing
Y
.On the VM, determine your username by running the following command:
whoami
You need this username later.
You can now configure the PuTTY app to use IAP TCP forwarding:
- Open the PuTTY app and select the category Connection > Proxy.
Configure the following proxy settings:
- For Proxy type, select Local.
In the Telnet command, or local proxy command field, enter the following:
gcloud.cmd compute start-iap-tunnel %host %port --listen-on-stdin --project PROJECT_ID --zone ZONE
Replace the following:
- PROJECT_ID: Project ID of the project the VM instance is located in
- ZONE: Zone where the VM instance is located
For Print proxy diagnostics in the terminal window, selectOnly until session starts.
Select the category Connection > SSH > Auth.
Click Browse and paste the following file name, then click Open:
%USERPROFILE%\.ssh\google_compute_engine.ppk
Select the category Session.
Configure the following proxy settings:
In the Host name (or IP address) field, enter the following:
USERNAME@INSTANCE_NAME
Replace the following:
- USERNAME: the Linux username you determined earlier
- INSTANCE_NAME: the name of the VM instance that you want to connect to
Saved sessions: Enter a name for the session.
Click Save.
Click Open to start the SSH session.
ssh
You can directly use the ssh command with a ProxyCommand
option that uses gcloud
to start the tunnel. Use this to generate the full ssh
command:
gcloud compute ssh INSTANCE_NAME --dry-run
Tunneling RDP connections
You can connect to Windows instances that don't have an external IP addressby tunneling RDP traffic through IAP:
IAP Desktop
You can use IAP Desktop to connect to the Remote Desktop of one or more VM instances by using IAP TCP forwarding.
In the application, select File > Add Google Cloud project.
Enter the ID or name of your project and click OK.
In the Project Explorer window, right-click the VM instance youwant to connect to and select Connect.
For more information on IAP Desktop, see theGitHub project page.
gcloud
To connect to the Remote Desktop of a VM instance, you first create a tunnel.
Use thegcloud compute start-iap-tunnelcommand to create an encrypted tunnel to the RDP port of the VM instance.
gcloud compute start-iap-tunnel INSTANCE_NAME 3389 \ --local-host-port=localhost:LOCAL_PORT \ --zone=ZONE
Replace INSTANCE_NAME with the name of the VM instance youwant to connect to. Replace LOCAL_PORT with the localhostport where you want the proxy to be bound or use 0 to have an unused oneselected automatically. Replace ZONE with the zone where theVM instance is located.
gcloud
performs a connectivity test with the VM instance, then opens atunnel and shows a port number.Listening on port [LOCAL_PORT].
All traffic sent to localhost:LOCAL_PORT is forwarded to theVM instance. The port is only accessible by applications running on yourlocal computer.
Leave
gcloud
running and open the Microsoft Windows Remote DesktopConnection app.Enter the tunnel endpoint as computer name:
localhost:LOCAL_PORT
Replace LOCAL_PORT with the port number shown when the tunnelwas opened by
gcloud
.Click Connect.
Tunneling other TCP connections
You can use IAP TCP forwarding for other TCP-based protocols byusing thegcloud compute start-iap-tunnelcommand to allocate a local port. The local port tunnels data traffic from thelocal machine to the remote machine in an HTTPS stream. IAPthen receives the data, applies access controls, and forwards the unwrapped datato the remote port. Conversely, any data from the remote port is also wrappedbefore it's sent to the local port where it's then unwrapped.
gcloud
Create an encrypted tunnel to a port of the VM instance:
gcloud compute start-iap-tunnel INSTANCE_NAME INSTANCE_PORT \ --local-host-port=localhost:LOCAL_PORT \ --zone=ZONE
Replace INSTANCE_NAME and INSTANCE_PORT with the nameand port of the VM instance you want to connect to. ReplaceLOCAL_PORT with the localhost port where you want the proxy to bebound. Replace ZONE with the zone where the VM instance islocated.
gcloud
performs a connectivity test with the VM instance, then opens atunnel and shows a port number.
Listening on port [LOCAL_PORT].
All traffic sent to localhost:LOCAL_PORT is forwarded to the VMinstance. The port is only accessible by applications running on your localcomputer.
Increasing the IAP TCP upload bandwidth
To increase the IAP TCP upload bandwidth consider installing NumPy in the same machine where gcloud CLI is installed.
Linux
To install NumPy using pip in Unix platforms, run the following command in a new terminal instance:
$(gcloud info --format="value(basic.python_location)") -m pip install numpyFor more information see: NumPy.org
If the error message persists after installing NumPy, complete the following step:Run the following command to allow gcloud to access external packages:
export CLOUDSDK_PYTHON_SITEPACKAGES=1
Windows
To install NumPy using pip in Windows platforms, run the following command in a new PowerShell instance:
start (gcloud info --format="value(basic.python_location)") "-m pip install numpy"For more information see: NumPy.org
If the message still persists after installing NumPy, another step is necessary.Run the following command to allow gcloud to access external packages:
$env:CLOUDSDK_PYTHON_SITEPACKAGES="1"
Known limitations
Bandwidth: IAP's TCP forwarding feature isn't intendedfor bulk transfer of data. IAP reserves the right torate-limit users abusing this service.
Connection length: IAP automatically disconnects sessionsafter 1 hour of inactivity. We recommend having logic in your applicationsto handle reestablishing a tunnel when it becomes disconnected.
Next steps
See access requests by enabling Cloud Audit Logs.
Configure VPC Service Controls to protect yourproject with IAP for TCP.